KitTools (2.1.4)

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

On this page

#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

#From Marketplace (Recommended)

# 1. Add the WashingBearLabs marketplace
/plugin marketplace add WashingBearLabs/WashingBearLabsMarketplace

# 2. Install the plugin
/plugin install kit-tools@washingbearlabs

#From Local Clone

git clone https://github.com/WashingBearLabs/KitTools.git

/plugin 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:seed-template`	Seed a single template with project-specific content
`/kit-tools:validate-seeding`	Validate seeded templates for unfilled placeholders
`/kit-tools:migrate`	Migrate a v1.x project to v2.0+ structure (includes vision/brief migration)
`/kit-tools:start-session`	Git health check, 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:create-vision`	Define the product vision interactively
`/kit-tools:plan-feature`	Create a Feature Spec for a new feature
`/kit-tools:complete-feature`	Mark a feature spec as completed and archive it
`/kit-tools:sync-project`	Full sync between code and docs (`--quick` for audit)
`/kit-tools:validate-feature`	Validate a feature branch against its feature spec (quality, security, compliance)
`/kit-tools:update-kit-tools`	Update project components from latest plugin versions
`/kit-tools:execute-feature`	Execute feature spec stories autonomously, supervised, or guarded
`/kit-tools:execution-status`	Check progress and status of autonomous execution
`/kit-tools:sync-symlinks`	Force-refresh skill symlinks after a plugin update

#Hooks Reference

KitTools includes automation hooks that run automatically:

Hook	Trigger	What it does
`create_scratchpad`	SessionStart	Creates SESSION_SCRATCH.md if kit_tools exists
`sync_skill_symlinks`	SessionStart	Syncs skill symlinks for the plugin
`update_doc_timestamps`	PostToolUse (Edit/Write)	Updates “Last Updated” in kit_tools docs
`detect_phase_completion`	PostToolUse (Edit)	Notes feature spec criteria and milestone task completions; suggests validate-feature when all criteria are done
`validate_seeded_template`	PostToolUse (Edit/Write)	Validates seeded templates for unfilled placeholders
`remind_scratchpad_before_compact`	PreCompact	Reminds to capture notes, adds compaction marker
`check_execution_notifications`	UserPromptSubmit	Surfaces execution notifications (completions, failures, crashes, pauses) on next user message
`remind_close_session`	Stop	Reminds to run close-session if scratchpad has notes

Note: Setup validation is built into /kit-tools:init-project as a final step.

#Project Structure

After initialization, your project will have:

your-project/
├── kit_tools/
│   ├── AGENT_README.md      # AI navigation guide
│   ├── SYNOPSIS.md          # Project overview
│   ├── PRODUCT_VISION.md    # Product vision (blank; populate via create-vision)
│   ├── SESSION_LOG.md       # Session history
│   ├── AUDIT_FINDINGS.md    # Code quality findings
│   │
│   ├── arch/                # Architecture docs
│   │   ├── CODE_ARCH.md     # Code structure, patterns
│   │   ├── DECISIONS.md     # Architectural decision records
│   │   ├── SERVICE_MAP.md   # Dependencies, integrations *
│   │   ├── INFRA_ARCH.md    # Cloud resources, networking *
│   │   ├── DATA_MODEL.md    # Database schema *
│   │   ├── SECURITY.md      # Auth, secrets, permissions *
│   │   └── patterns/        # Detailed pattern docs (optional)
│   │
│   ├── docs/                # Operational docs
│   │   ├── LOCAL_DEV.md     # Local development setup
│   │   ├── CONVENTIONS.md   # Code conventions
│   │   ├── TROUBLESHOOTING.md
│   │   ├── GOTCHAS.md       # Known issues
│   │   ├── MONITORING.md    *
│   │   ├── CI_CD.md         *
│   │   ├── DEPLOYMENT.md    *
│   │   ├── API_GUIDE.md     *
│   │   ├── ENV_REFERENCE.md *
│   │   ├── UI_STYLE_GUIDE.md *
│   │   └── feature_guides/
│   │
│   ├── testing/             # Test documentation
│   │   └── TESTING_GUIDE.md
│   │
│   ├── specs/               # Feature specs and epics
│   │   └── archive/         # Completed feature specs
│   │
│   ├── roadmap/             # Milestone tracking
│   │   ├── MILESTONES.md
│   │   └── BACKLOG.md
│   │
│   └── hooks/               # Automation scripts (installed by init-project)
│       ├── create_scratchpad.py
│       ├── update_doc_timestamps.py
│       └── ...              # 7 scripts total
│
└── CLAUDE.md                # Claude Code instructions

* Project-type-specific — included for API/Backend, Web App, Full Stack, etc. See Project Types for which templates are included with each type.

#Templates Reference

KitTools provides 30 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
`SESSION_LOG.md`	Session history
`AUDIT_FINDINGS.md`	Code quality findings log
`CODE_ARCH.md`	Code architecture — structure, patterns, key abstractions
`DECISIONS.md`	Architecture decision records
`LOCAL_DEV.md`	Local development setup
`GOTCHAS.md`	Known issues and landmines
`CONVENTIONS.md`	Code conventions and standards
`TROUBLESHOOTING.md`	Common issues and solutions
`TESTING_GUIDE.md`	Testing strategy and patterns
`PRODUCT_VISION.md`	Product vision (via create-vision skill)
`specs/*`	Feature specs and epics
`roadmap/*`	Milestone tracking and backlog

#API (For backend services)

Template	Purpose
`API_GUIDE.md`	API documentation
`DATA_MODEL.md`	Database schema
`ENV_REFERENCE.md`	Environment variables
`SERVICE_MAP.md`	Dependencies and integrations

#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
`SECURITY.md`	Security documentation

#UI (For frontend applications)

Template	Purpose
`UI_STYLE_GUIDE.md`	UI patterns and component guidelines
`feature_guides/FEATURE_TEMPLATE.md`	Feature-specific documentation template

#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 + UI
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  │  ← Git check, 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"]
**Feature Spec:** [e.g., `feature-auth.md` or N/A]

---

## Notes

[Notes captured during the session]

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

#Feature Validation

Use /kit-tools:validate-feature to validate an entire feature branch against its feature spec:

Captures the full branch diff (git diff main...HEAD) — all changes across the feature
Runs three independent review passes:
- Code Quality — naming, patterns, code smells, error handling (dedicated agent)
- Security — injection, auth gaps, secrets, input validation (dedicated agent)
- Feature Spec Compliance — acceptance criteria coverage, scope creep, intent alignment
Runs the project’s test suite — auto-detects the test command (package.json, pyproject.toml, pytest.ini, Makefile, or TESTING_GUIDE.md). Failed tests are logged as critical findings.
Fixes critical findings automatically (autonomous mode) or inline (supervised mode)
Writes remaining findings to kit_tools/AUDIT_FINDINGS.md with unique IDs and severity levels
Critical findings pause autonomous execution — a .pause_execution file is created referencing the findings. Warning and info findings do not pause. In supervised mode, findings are reported without pausing.

Validation runs automatically after autonomous execution completes, and can be invoked manually at any time. Open findings are reviewed at /kit-tools:start-session.

#Feature Planning

Use /kit-tools:plan-feature to create Feature Specs:

Optional Product Vision for strategic context (define with /kit-tools:create-vision)
Interactive questions refine scope and requirements
Epic detection — Large features are automatically decomposed into multiple feature specs with an explicit epic file
Generates feature-[name].md with:
- Overview and goals
- User stories with acceptance criteria (US-XXX format)
- Implementation hints per story (key files, patterns, gotchas)
- Out of scope boundaries
- Technical considerations
Story refinement — Each story is reviewed for session-fit before finalizing
- Implementation hints are generated during refinement to reduce agent exploration time
- Test criteria auto-injected — Code stories automatically get “Tests written/updated” and “Full test suite passes” criteria (doc/config-only stories are exempt)
Links to backlog and milestone tracking
Captures implementation notes and refinement notes as you work

#Story Refinement

After generating the feature spec, each story is reviewed against these heuristics:

Check	Question	Red Flag
Single Responsibility	Is this story doing multiple things?	“and”, “also”, multiple verbs
Session Fit	Can this complete in one context window?	Touches >3 files, crosses subsystems
Research Needs	Are there unknowns that would eat context?	Vague tech, unexplored patterns
Scope Clarity	Are criteria specific and verifiable?	“works correctly”, “handles properly”

For each story with issues, the refinement process:

Multi-concern stories → Split into separate stories
Over-scoped stories → Narrow or split
Research needs → Conduct research, document findings
Vague criteria → Propose specific, verifiable criteria

Refinement findings are captured in the feature spec’s “Refinement Notes” section.

#Session-Fit Guidelines

Feature specs are sized for reliable autonomous execution:

Guideline	Target
Stories per feature spec	5-7 (max 7)
Criteria per story	3-5 (max 6)
Total criteria	≤35

Feature specs exceeding these limits are flagged as session_ready: false and should be decomposed.

#Epic Decomposition

Large features (“epics”) are automatically split into focused feature specs with an explicit epic file:

"OAuth Authentication" (epic)
         ↓ decomposed into:
├── epic-oauth.md              (decomposition table, completion criteria)
├── feature-oauth-schema.md    (3 stories, no dependencies)
├── feature-oauth-provider.md  (4 stories, depends_on: [oauth-schema])
├── feature-oauth-api.md       (4 stories, depends_on: [oauth-provider])
└── feature-oauth-ui.md        (4 stories, depends_on: [oauth-api])

When you run /kit-tools:execute-feature on any feature spec in an epic, the orchestrator detects the epic and offers to execute all remaining specs in sequence on a shared epic/[name] branch. Each spec is validated, tagged, and archived before the next one starts. Dependencies are enforced as hard gates — a spec won’t execute until its depends_on specs are archived.

#Feature Spec Lifecycle

/plan-feature → feature-auth.md (status: active, session_ready: true)
       ↓
/execute-feature → implement stories on feature/auth branch
       ↓
/validate-feature → quality, security, and compliance review
       ↓
/complete-feature → archive feature spec, clean up artifacts, handle branch

#Feature Spec Structure

---
feature: auth
status: active
session_ready: true   # true if all stories pass refinement
depends_on: []
vision_ref:           # product vision reference (optional)
type: feature         # feature (default) or epic-child
epic:                 # epic name (empty for standalone specs)
epic_seq:             # execution order within epic (1-based)
epic_final:           # true only on last spec in epic
created: 2025-01-15
updated: 2025-01-20
---

# Feature Spec: User Authentication

## Overview
Brief description of the feature and the problem it solves.

## Goals
- Specific, measurable objective 1
- Specific, measurable objective 2

## User Stories

### US-001: User Login Form

**Description:** As a user, I want to see a login form so that I can enter my credentials.

**Implementation Hints:**
- Reuse existing Form component at `src/components/Form.tsx`
- Follow validation patterns in `src/utils/validators.ts`

**Acceptance Criteria:**
- [ ] Login page shows email and password fields
- [ ] Submit button is disabled until both fields have content
- [ ] Tests written/updated for new functionality
- [ ] Full test suite passes
- [ ] Typecheck/lint passes

### US-002: Login Authentication

**Description:** As a user, I want my credentials validated so that I can access my account.

**Implementation Hints:**
- AuthService at `src/services/auth.ts` handles credential validation
- Dashboard route at `/dashboard` — redirect on success

**Acceptance Criteria:**
- [ ] Valid credentials redirect to dashboard
- [ ] Invalid credentials show error message
- [ ] Tests written/updated for new functionality
- [ ] Full test suite passes
- [ ] Typecheck/lint passes

## Out of Scope
- What this feature will NOT include

## Implementation Notes
<!-- Populated during implementation -->

## Refinement Notes

### Research Conducted
- Existing auth uses AuthService at src/services/auth.ts
- Dashboard route at /dashboard

### Scope Adjustments
- Original US-001 split into US-001 (form) and US-002 (auth)

### Decisions Made
- Reuse existing AuthService for credential validation

#Autonomous Execution

Use /kit-tools:execute-feature to execute feature spec stories:

/kit-tools:execute-feature    # Select feature spec, choose execution mode, run

Three execution modes:

Supervised — Review each story in-session before continuing
Autonomous — Spawn separate Claude sessions per story, run until complete
Guarded — Autonomous with human oversight on failures

Key features of autonomous execution:

Branch-per-attempt — Each implementation attempt runs on a temporary branch (feature-story-attempt-N). Successful attempts merge; failed attempts are deleted cleanly (no destructive git reset).
File-based agent results — Agents write structured JSON result files instead of stdout parsing, eliminating false failures from LLM output formatting.
Reference-based context — Agent prompts pass file paths instead of inlining full file contents, reducing prompt size ~80% for large projects.
Implementation hints — Per-story hints from planning flow reduce exploration time.
Independent verification — A separate verifier agent receives git-sourced file lists (not implementer claims) for honest assessment.
Patch-based retry — Failed attempt diffs are included in retry prompts so the agent takes a different approach.
Pause on critical findings — After validation, critical findings create a .pause_execution file. The pipeline resumes when the file is removed after review.

Progress is tracked in kit_tools/EXECUTION_LOG.md and feature spec checkboxes.

For epics, the orchestrator chains feature specs automatically — executing all stories in one spec, validating, tagging a checkpoint, archiving, then moving to the next. You can choose to pause between specs for review or run non-stop.

#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]

#AUDIT_FINDINGS.md

Code quality findings from validation:

## Active Findings

### [AUD-001] Finding Title
- **Severity:** critical / warning / info
- **File:** path/to/file.ts:42
- **Description:** What was found
- **Recommendation:** How to fix it

#Template Versioning

All templates include version comments:

<!-- Template Version: 1.2.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

#Links

#License

GPL-3.0 License