KitTools (1.6.4)

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 — Create PRDs 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 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`	Create a Product Requirements Document (PRD) for a new feature
`/kit-tools:complete-feature`	Mark a PRD 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 PRD (quality, security, compliance)
`/kit-tools:update-kit-tools`	Update project components from latest plugin versions
`/kit-tools:execute-feature`	Execute PRD 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/Write)	Notes PRD criteria and TODO task completions; suggests validate-feature when all PRD 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
│   ├── SESSION_LOG.md       # Session history
│   ├── AUDIT_FINDINGS.md    # Code quality findings
│   │
│   ├── 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
│   │   ├── CONVENTIONS.md   # Code conventions
│   │   ├── TROUBLESHOOTING.md
│   │   ├── MONITORING.md
│   │   ├── CI_CD.md
│   │   ├── DEPLOYMENT.md
│   │   ├── API_GUIDE.md
│   │   ├── ENV_REFERENCE.md
│   │   ├── UI_STYLE_GUIDE.md
│   │   ├── GOTCHAS.md       # Known issues
│   │   └── feature_guides/
│   │
│   ├── testing/             # Test documentation
│   │   └── TESTING_GUIDE.md
│   │
│   ├── prd/                 # Product Requirements Documents
│   │   └── archive/         # Completed PRDs
│   │
│   └── roadmap/             # Milestone tracking
│       ├── MVP_TODO.md
│       └── BACKLOG.md
│
└── CLAUDE.md                # Claude Code instructions

Templates Reference

KitTools provides 29 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
`prd/*`	Product Requirements Documents
`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  │  ← 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"]
**PRD:** [e.g., `prd-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 PRD:

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)
- PRD Compliance — acceptance criteria coverage, requirement fulfillment, scope creep
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 with PRDs

Use /kit-tools:plan-feature to create Product Requirements Documents (PRDs):

Interactive questions refine scope and requirements
Epic detection — Large features are automatically decomposed into multiple PRDs
Generates prd-[name].md with:
- Overview and goals
- User stories with acceptance criteria (US-XXX format)
- Implementation hints per story (key files, patterns, gotchas)
- Functional requirements (FR-X format)
- Non-goals and 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 PRD, 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 PRD’s “Refinement Notes” section.

Session-Fit Guidelines

PRDs focus on session-fit per story rather than story counts:

Guideline	Target
Single responsibility	One concern per story
Session fit	Completable in one context window
Acceptance criteria	3-5 per story, clear and verifiable

Story count is not a target — a PRD with 15 well-refined stories is fine. What matters is that each story passes refinement checks.

PRDs are marked session_ready: true if all stories pass refinement; session_ready: false if refinement was skipped or stories have unresolved issues.

Epic Decomposition & Chaining

Large features (“epics”) are automatically split into focused PRDs with chaining fields:

"OAuth Authentication" (epic)
         ↓ decomposed into:
├── prd-oauth-schema.md    (epic_seq: 1, no dependencies)
├── prd-oauth-provider.md  (epic_seq: 2, depends_on: [oauth-schema])
├── prd-oauth-api.md       (epic_seq: 3, depends_on: [oauth-provider])
└── prd-oauth-ui.md        (epic_seq: 4, epic_final: true, depends_on: [oauth-api])

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

PRD Lifecycle

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

PRD Structure

---
feature: auth
status: active
session_ready: true   # true if all stories pass refinement
depends_on: []
epic:                 # epic name (empty for standalone PRDs)
epic_seq:             # execution order within epic (1-based)
epic_final:           # true only on last PRD in epic
created: 2025-01-15
updated: 2025-01-20
---

# PRD: 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

## Non-Goals
- 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 PRD stories:

/kit-tools:execute-feature    # Select PRD, 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 PRD checkboxes.

For epics, the orchestrator chains PRDs automatically — executing all stories in one PRD, validating, tagging a checkpoint, archiving, then moving to the next. You can choose to pause between PRDs 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

License

GPL-3.0 License