KitTools (2.4.3)

A framework for AI-assisted development. Structured documentation, autonomous execution, and guided workflows.

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 & execution — Plan epics, validate specs, and execute stories autonomously

Structured documentation, autonomous execution, and guided workflows — built for Claude Code. 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: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-epic`	Plan a new feature or epic, creating an Epic and Feature Specs
`/kit-tools:validate-epic`	Validate feature specs before execution — completeness, story quality, adversarial review, codebase fit, cross-model second opinion
`/kit-tools:execute-epic`	Execute an epic’s feature specs autonomously, supervised, or guarded — with optional supervisor monitoring
`/kit-tools:complete-implementation`	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-implementation`	Validate a feature branch against its feature spec (quality, security, compliance)
`/kit-tools:execution-status`	Check progress and status of autonomous epic execution; acts as supervisor when monitoring is enabled
`/kit-tools:optimize-tests`	Audit test suite health: mapping gaps, stale tests, overlap, performance, KitTools alignment

#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
`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-implementation 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
│   │   └── test-metrics.json  # Auto-generated test metrics from orchestration
│   │
│   ├── 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-implementation 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-epic to create epics and feature specs:

Optional Product Vision for strategic context (define with /kit-tools:create-vision)
Interactive questions refine scope and requirements
Scope assessment — Determines how many feature specs the work requires (1 for simple, 2-5+ for complex). All work is structured as an epic, even single-spec features.
Generates epic-[name].md + feature-[name].md files with:
- Epic overview and completion criteria
- 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
Run /kit-tools:validate-epic before execution to catch gaps early

#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	5-7 (max 10)
Total criteria	≤49

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-epic, the orchestrator reads the epic’s decomposition table and executes specs in order 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-epic → epic-auth.md + feature-auth-schema.md + feature-auth-api.md
       ↓
/validate-epic auth → catch gaps before coding starts
       ↓
/execute-epic auth → autonomous execution, story by story
       ↓
/validate-implementation → quality, security, and compliance review
       ↓
/complete-implementation → archive feature specs, 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-epic to execute feature spec stories:

/kit-tools:execute-epic    # Select epic, 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

Supervisor monitoring (optional, for autonomous/guarded modes): When enabled, the launching Claude session stays active as a supervisor, polling orchestrator health every 30 minutes. The supervisor can:

Detect crashes and stale heartbeats
Split oversized stories that repeatedly time out
Pause execution when problems persist after intervention
Skip blocked stories and continue with the rest

The supervisor communicates with the orchestrator through JSON files (health snapshots and control actions) — no system-level permissions required from the Claude session. Intervention follows a graduated path: observe retries → intervene after exhaustion → escalate to user.

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.
Test metrics — Per-file test pass/fail counts, durations, and timeouts are tracked in kit_tools/testing/test-metrics.json across orchestration runs for identifying slow or flaky tests.
24-hour safety net — Orchestrator self-terminates after 24 hours of continuous execution.

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

To pick up new templates or hooks from a newer plugin version, run /plugin update kit-tools@washingbearlabs and then re-run /kit-tools:init-project in your project to merge in the additions.

#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