KitTools Release Notes

Back to KitTools Docs

KitTools ships for both Claude Code and GitHub Copilot CLI, maintained in version lockstep — these notes apply to both builds. See Claude Code vs. Copilot CLI for how the builds differ.

---

#2.9.1 — 2026-07-18

Two correctness fixes surfaced by running real autonomous epics: completed specs weren’t actually being marked complete, and a rare double-launch could make a healthy run look crashed.

#Fixed

• Archived feature specs weren’t actually marked complete — a completed spec is supposed to be updated to status: completed (with a completion date) before moving to the archive, but a bug meant every spec generated from this plugin’s own templates kept showing status: active forever, even after the feature had shipped. Archiving now correctly updates the spec’s status every time.
• A guarded run could briefly show as “crashed” while completely healthy — if an orchestrator process was ever accidentally launched twice against the same project (for example, pasting a manual resume command a second time), the second process could stamp the first, still-running process’s status as crashed — and in rare cases could even kill its session outright. KitTools now refuses to launch a second orchestrator against a project that already has one running, and a process can no longer alter a run’s status or session unless it’s the one that actually owns it.

---

#2.9.0 — 2026-07-15

The telemetry KitTools already collects locally now carries what’s needed to run controlled experiments on it — did tightening a knob (validation depth, escalation policy) actually change outcomes?

#Added

• Experiment tracking fields — optional experiment_id/arm labels (set by an external harness, never by KitTools itself) and a deterministic scaffold “fingerprint” now travel with every run record under ~/.kit/feedback/, so runs that used an identical configuration can be grouped and compared even without manually tagging them.
• Git provenance on every run record — each one now carries the repo’s origin URL and, per feature spec, the commit that spec’s work actually landed on — a traceable link between a run record and the code it produced.
• Escalation policy is now configurable — the model-escalation-on-retry trigger (which retry attempt, which spec sizes) used to be fixed in code; it’s now a model_config.escalation setting alongside the existing per-role model overrides.
• validate-epic records which reviewer tier ran — full 6-reviewer panel vs. the small-epic quick tier is now recorded on the run, not just inferable from a shorter results table.

#Changed

• The local telemetry format is now documented as a stable, versioned interface — for anyone building tooling on top of ~/.kit/feedback/, not just KitTools’ own internals.

---

#2.8.5 — 2026-07-01

Three refinements from real use: no more arbitrary planning limits, faster validation, and a mixed-language execution fix.

#Changed

• No more arbitrary size limits on epics, specs, or stories — planning used to nudge specs and stories toward target counts (so many criteria per story, and so on), which pressured real work into an artificial shape — leaving stories vague, or merging specs that should have stayed separate. Those numeric limits are gone. An epic now has as many specs as the work’s distinct concerns require, a spec as many stories as its concern needs, and a story as many acceptance criteria as precision demands — with no ceiling. The only rule is scope: a unit is split when it covers more than one concern, never to hit a number. Precise, detailed specs are the goal, not conformance to a shape.
• Validation runs everything in parallel — /kit-tools:validate-epic used to review one spec at a time; it now fans out every reviewer for every spec at once and returns a single consolidated findings view, so you see the whole picture immediately instead of wading through it spec by spec. validate-implementation and validate-seeding fan out their reviewers too.

#Fixed

• Mixed Python + JavaScript/TypeScript repos no longer trip a false regression — the regression safety-check was hardcoded to a Python test runner and would hand it a TypeScript test file, fail to find it, mistake that for a broken test, and roll back a perfectly good change. Test files are now routed to the runner that owns them (by file type), each run from its own package — and anything it can’t run (an unknown type, a missing tool) is safely skipped rather than treated as a failure.

---

#2.8.4 — 2026-06-25

A small efficiency fix for autonomous execution.

#Changed

• No more redo-from-scratch over trivial formatting — when an implementer finished a story that was functionally complete but had a mechanically-fixable lint issue (import ordering, quote style), the run used to throw the whole thing away and re-implement it from scratch. The implementer now cleans up formatting and auto-fixable lint on its changed files (and re-runs the relevant tests) before handing off — so good work isn’t discarded over cosmetics. Fully language-agnostic: it uses whatever formatter/linter your project already has. Lint that genuinely needs a human’s judgment is still caught and addressed as real work.

---

#2.8.3 — 2026-06-25

A planning-guidance refinement: epics are no longer nudged toward an arbitrary number of specs.

#Changed

• Plan as big as the work actually is — /kit-tools:plan-epic no longer tiers spec count by a “complexity” bucket. An epic now gets as many feature specs (and stories, and acceptance criteria) as the work genuinely requires — no target, no upper bound. Decomposition is driven by scope (split a spec that covers two unrelated concerns; merge a fragment that can’t stand on its own), not by hitting a number. The precision rules that keep each unit sharp still apply (a single story that grows past ~10 criteria still gets split rather than bloated), and validation was checked end-to-end so a large, well-scoped epic is never penalized just for its size.

---

#2.8.2 — 2026-06-24

Two quality-of-life improvements for long, unattended runs.

#Added

• Keep the machine awake during a run — autonomous/guarded execution now offers (at setup, default off) to hold the machine awake for the duration of the run, so a laptop sleeping overnight no longer suspends your epic mid-way. Idle/system sleep is prevented while the display is still free to sleep, and the assertion releases automatically when the run finishes. Built on the OS’s own facilities (macOS caffeinate, Linux systemd-inhibit); on anything else it quietly does nothing.

#Changed

• The supervisor stops on its own — with monitoring enabled, the supervisor used to keep checking every 30 minutes even after a run had finished or got blocked waiting on you. Now it stands down automatically the moment the run ends or hits something only you can resolve (and you get a desktop notification when it needs you), so it doesn’t keep polling while you’re away. It still stays alive through pauses it can heal itself.

---

#2.8.1 — 2026-06-23

A reliability fix release for the run trace, from a post-release review.

#Fixed

• Completed runs are now actually recorded — autonomous runs were logging in-progress telemetry but almost never their final completed/failed outcome (a run’s terminal status is set after its last working session ends, so the telemetry hook never saw it). The orchestrator now records the terminal result itself at the end of a run — with the real outcome, token usage, and cost — so “did this run succeed, and what did it cost?” is finally answerable from the trace.
• A failed session can’t masquerade as success — when a working session fails at the agent level (e.g. it runs out of context) but still exits cleanly, it’s now correctly treated as a failure and retried, instead of being mistaken for a successful result.
• Re-validating an epic no longer piles up telemetry — re-running validation on the same epic now updates a single record (latest pass wins) rather than adding a new one each time.
• Trace writes are fully fail-safe — hardened so a telemetry write can never interrupt or slow a run, even on an unexpected payload.

#Added

• Runs record the settings they used — each run now captures the configuration it executed with (models, completion strategy, isolation mode), so outcomes can be compared across configurations. New reliability signals are also recorded: when a human steps in (skip/split/abort) and when a run recovers from a git conflict. And a spec’s pre-execution quality scores can now be tied to how that spec’s implementation actually turned out.

---

#2.8.0 — 2026-06-18

A measurement release: /kit-tools:validate-epic now scores how execution-ready each spec is, so the “re-run validation or just execute?” call stops being a gut check — and every autonomous run now emits a structured, per-run trace (with real token and cost figures), the foundation for benchmarking and learning from past runs.

#Added

• Per-reviewer readiness scores — Each of the six /kit-tools:validate-epic reviewers now returns a 1–10 readiness score for how execution-ready it judges the spec, anchored to its verdict (a critical finding caps the score low; a clean pass scores high). Scores are reported as a per-reviewer vector — never averaged — so a high score from one reviewer against a low score from another is visible signal worth digging into, and the gate reads the worst reviewer. The recurring “do we re-run validation or just execute?” decision becomes legible instead of a judgment call on the findings list.
• Structured run trace — Every autonomous run now emits a typed, append-only event stream covering its whole lifecycle (run start, each story’s implement / verify / retry / model-escalation, merges, completion), not just failures. Each run gets a stable id, and the trace records real token usage and cost per session — kept honestly separate from rough estimates, so an unmeasured run is never shown as free. This is the substrate for measuring and comparing runs over time.
• Spec quality lands in the trace — /kit-tools:validate-epic records its per-reviewer readiness scores into the same trace, so a spec’s pre-execution quality can later be related to how its implementation actually turned out.

#Changed

• Telemetry is now a clean per-run record — The Stop-time signal capture was rewritten from a best-effort log scrape into a deterministic reducer over the run’s event stream. It produces one structured record per run (idempotent — re-running never double-counts), captures reliability signals (productive review cycles vs. thrashing, retries, escalations, merges that actually landed), and no longer deletes any source files. Records live under ~/.kit/feedback/ and survive plugin updates.

---

#2.7.0 — 2026-06-10

A planning-rigor release: feature planning now front-loads the discipline that used to be discovered late by reviewers — plus a new plugin health check, an optional web-research agent so you stop designing in a vacuum, and a hardening pass on the execution engine’s error handling.

#Added

• /kit-tools:doctor — plugin health check — Verifies the things that otherwise only fail mid-workflow: every agent and script a skill references actually exists, agent prompt contracts haven’t drifted, all automation scripts compile, and your environment can run the plugin (tmux for autonomous execution, required Python deps, git). It also detects when your active install is stale or behind the latest release. Runs automatically at the end of /kit-tools:init-project, and anytime on demand. All findings are advisory with suggested fixes.
• Landscape researcher — stop designing in a vacuum (optional) — Both /kit-tools:create-vision and /kit-tools:plan-epic can now launch a web-research agent that surveys prior art and similar projects, current techniques and papers, candidate libraries, and known pitfalls — and when you’re revisiting an existing design, reports specifically where the field has moved since it was written. The skills suggest it automatically when an idea touches AI features or fast-moving territory (you may not know you’re on the bleeding edge — the tooling watches for it), but you always make the call. Every finding carries a source link and date, and results are presented as leads for you to evaluate, never silently incorporated.
• Shift-left planning — /kit-tools:plan-epic got a structural upgrade so problems get prevented at planning time instead of caught by reviewers afterward:
  • Clarification scan — instead of a few generic questions, the draft scope is checked against a 7-category taxonomy (scope, data, integrations, edge cases, non-functional, security, completion signals) and up to 5 high-impact questions are asked, each with a recommended answer. Every Q&A is logged to a Clarifications audit trail in the spec.
  • Research before stories — the codebase is explored before stories are written, so implementation hints point at code that actually exists.
  • Blocking questions gate execution — open questions are now classified; an unresolved blocking question marks the spec not-ready, instead of letting the implementing agent hit the unknown mid-run.
  • Richer specs — feature specs gain Edge Cases (each owned by a story), Assumptions (the defaults you settled during planning, so the implementer doesn’t re-guess them), and measurable success-criteria guidance.
  • Prioritized, independently-testable stories — every story carries a P1–P3 priority and an “independent test” statement, making MVP-first decomposition explicit and giving the execution supervisor principled decisions when a low-priority story struggles.
• Quick validation tier — for small, low-risk epics, /kit-tools:validate-epic can suggest a 3-reviewer quick pass instead of the full 6-reviewer panel. The full panel stays the default and you always choose.
• Learnings compaction — /kit-tools:close-session now compacts the execution learnings accumulated across epics: near-duplicate lessons are merged, and recurring ones get promoted into your permanent GOTCHAS/CONVENTIONS docs.

#Changed

• Prompt-injection defenses in every agent — all agents now carry a security preamble tailored to the content they read (code, specs, templates, web pages), enforced automatically so future agents can’t ship without one. Several agents that previously had none — including the one that explores your source code — are now covered.
• One verdict vocabulary — every review agent now reports a common ready / needs-work / not-ready verdict alongside its native format, so results aggregate consistently across the whole pipeline.
• Skill telemetry survives plugin updates — retrospective signals now live in a per-user location instead of the plugin install directory, where each update used to strand them.
• Clearer skill behavior in edge cases — seven previously-ambiguous behaviors are now explicit, including what happens when the worktree contract is missing, who cleans up copied secrets, and how the cross-model second-opinion reviewer picks its model.

#Fixed

• Internal git failures now stop loudly — the orchestrator’s git helper had a flag that looked like it raised errors but only logged them — the root enabler of the 2.6.4 silently-dropped-work bug. Failures that can’t be safely ignored now halt execution with a clear alert; every call site was audited individually.
• Spec files can’t be truncated by a crash — story checkbox updates now write atomically, same as the execution state.
• Windows compatibility — persisting cross-epic learnings no longer crashes on platforms without Unix file locking.

---

#2.6.4 — 2026-06-10

A critical autonomous-execution fix: stories could be reported as shipped while their code silently never landed.

#Fixed

• No more silently-dropped work — Between stories, a tracked, constantly-rewritten execution log could block the internal branch switch the orchestrator uses to merge a finished story. The merge then quietly became a no-op the orchestrator read as success — so the story was marked complete and its checkboxes ticked while its commits never reached the branch. In one run this dropped most of a feature spec’s stories invisibly. The orchestrator now verifies every merge actually landed before recording success — and if a merge genuinely can’t proceed, it stops loudly with a clear alert instead of pretending it worked. The run log and audit findings are now treated as throwaway run artifacts (ignored by git, and auto-untracked on upgrade if a previous run committed them), removing the trigger entirely.
• Completed specs always reach the PR — Archiving a finished feature spec now verifies the move was actually captured by git, instead of letting an empty commit mask a failure that would leave the completed work out of the branch.
• Resuming a long run no longer instantly stops — The 24-hour safety net measured from when the epic first started, so resuming a run that began over a day ago tripped the auto-stop immediately. It now measures each launch fresh, so a resume gets a full window.

---

#2.6.3 — 2026-06-09

More autonomous-execution correctness fixes from live runs.

#Fixed

• size: hints now actually apply — A spec’s size: L/XL was silently ignored because the frontmatter parser didn’t look past the template’s leading version comment, so every template-generated spec ran at the default (medium) timeout — large stories timed out forever. The parser now finds the frontmatter regardless of leading comments, and warns when a spec’s frontmatter can’t be read.
• Failed retries no longer strand the worktree — If an implementation attempt left uncommitted changes (a killed or timed-out session), cleanup could get stuck on the half-finished branch and carry the mess into the next retry. Cleanup now forcibly resets to a clean state and sweeps stray files (your real config — .venv, .env — is preserved).
• Stopping a run stops its work — Stopping the orchestrator (Ctrl+C / kill / tmux) now also stops the underlying AI session it spawned. Previously that child could keep running and write partial, unverified changes after you’d stopped — re-dirtying your workspace.
• Guarded-mode pauses are visible — When a guarded run pauses after exhausting retries, it now shows up in /kit-tools:execution-status (and to the supervisor) as paused instead of looking like a hung run, and can be resumed by removing the pause file or by a supervisor skip/split action — no terminal keystroke required.

---

#2.6.2 — 2026-06-06

Correctness fixes for autonomous execution, from continued live runs.

#Fixed

• Validation fixes now reach the PR — When the post-spec validation step fixed a bug by editing source files directly, those edits could be left uncommitted — present in the working tree (so reviewers saw them as “fixed”) but missing from the pull request, shipping the bug to main. The orchestrator now commits the full worktree after each spec’s validation and before opening a PR, with a clean-tree invariant. (Safe because autonomous runs are isolated in their own worktree.)
• Completed runs reliably marked complete — On a clean finish, the execution is now recorded as completed in the registry before its state is cleaned up, so a successful run is never left looking like a crash and is reaped without manual intervention.

---

#2.6.1 — 2026-06-05

Field-hardening for worktree isolation, from the first real-world runs.

#Added

• Local & sibling path dependencies (path_links) — A fresh worktree has no siblings, so a project with a local path dependency (a Python path = "../Roots", a pnpm/yarn workspace pointing at ../shared, a Cargo path = "../crate") couldn’t install. The new path_links: key in worktree.yaml lists those paths; KitTools symlinks each at the worktree’s matching relative location, resolved from your main checkout — portable, with no machine-specific absolute path in the committed contract.

#Changed

• Smoother upgrades for older projects — /kit-tools:execute-epic now ensures .kit/ is gitignored before launching (so a project that predates worktree isolation can’t accidentally commit the registry) and offers to create worktree.yaml when it’s missing. Re-running /kit-tools:init-project cleanly retrofits these onto an existing project.
• Accurate status & clean teardown — Execution status now reflects live progress from the running worktree (not a frozen registration timestamp). On a clean finish the execution is reliably marked complete so it reaps without manual intervention, and teardown accounts for the per-project worktree directory: an empty one is removed, while one holding shared links reused by future runs is reported rather than deleted.

#Fixed

• A completed execution could remain marked “running” in the registry when its key and worktree name diverged, blocking automatic cleanup — completion now reconciles by worktree path, which can’t drift.

---

#2.6.0 — 2026-06-04

#Added

• Worktree isolation for autonomous execution — Autonomous and guarded epics now run in a dedicated git worktree (under ~/.kit/worktrees/) instead of your live checkout. The background orchestrator never shares a working directory with you, so you can keep editing, plan the next epic, or run a second execution in the same repo without contaminating each other’s commits or fighting over checked-out branches. Branch-per-epic is unchanged — what’s new is a separate working directory per execution. Supervised mode is unaffected (it stays an in-session flow in your checkout).
• Execution registry & safe teardown — A gitignored .kit/ registry tracks running executions so /kit-tools:execution-status, /kit-tools:close-session, and others find them from anywhere. When a run finishes, /kit-tools:complete-implementation and /kit-tools:close-session reap merged worktrees and flag (never destroy) any with unmerged or uncommitted work — leaning on git’s own safety guards.
• Worktree & environment contract — /kit-tools:init-project now creates a committed worktree.yaml where you declare how a fresh worktree becomes runnable: the install commands to run (env_bootstrap) and the gitignored secret files to link in (env_link). KitTools is language-agnostic, so the commands are yours to specify — and they’re echoed and confirmed before they run.

#Changed

• /kit-tools:init-project sets up git — It now offers to initialize a git repository on main (with an initial commit) when one doesn’t exist, and writes .gitignore rules for transient execution state — instead of assuming a repo was already there. If you bring an existing repo on master (or another default branch), KitTools detects and uses it automatically.
• Smarter completion & pre-flight — For worktree runs, “merge” completes server-side (push → PR merge) rather than touching your live checkout. /kit-tools:execute-epic checks git readiness up front and warns when a project has dependencies but no env_bootstrap configured (a fresh worktree wouldn’t have them installed, so tests would fail).
• Fully backward compatible — Existing in-place executions keep working untouched. To adopt worktree isolation in an existing project, update the plugin and re-run /kit-tools:init-project to add worktree.yaml and the .gitignore rules.

---

#2.5.0 — 2026-06-03

#Added

• Spec security reviewer — New adversarial security review agent for /kit-tools:validate-epic. Reviews feature specs for attack surface expansion, auth/authz gaps, data exposure risks, trust boundary violations, and security-relevant omissions before any code is written. Shift-left security catches design-level problems when they’re cheapest to fix.
• Bump version skill — New /kit-tools:bump-version skill with a customizable BUMP_VERSION.md runbook template. Define where your version lives, changelog conventions, additional files or repos to update, and commit format — the skill follows the runbook each time it runs. /kit-tools:complete-implementation offers to invoke it as an optional final step.

#Changed

• Validate-epic runs 6 reviewers — Security reviewer joins the existing five parallel reviewers (completionist, story quality, salty engineer, codebase fit, second opinion) for comprehensive pre-execution validation.
• Complete-implementation offers version bump — After archiving and cleanup, checks for a version runbook and offers to bump if present.

---

#2.4.3 — 2026-05-22

#Added

• Codebase fit reviewer — New review dimension for /kit-tools:validate-epic. Deeply explores the actual codebase to verify implementation hints, find missed reuse opportunities, check pattern conformance, and identify duplication risks. Every finding includes file paths and function names grounded in real code exploration.
• Signal feedback hook — New harvest_signals Stop hook silently captures skill telemetry from KitTools artifacts for retrospective analysis of skill performance across projects.

#Changed

• Validate-epic runs reviewers in parallel — All five reviewers now spawn concurrently instead of sequentially, with consolidated finding presentation and selective re-run of individual reviewers after spec updates.
• Epic pause behavior is mode-dependent — Autonomous and guarded modes now run continuously between specs. Supervised mode pauses between specs for user review. Previously, the default caused unintended pauses in autonomous/guarded execution.

#Fixed

• Autonomous/guarded epic pausing between specs — Example config and skill documentation hardcoded pause-between-specs as enabled, causing agents to set it regardless of execution mode.

---

#2.4.2 — 2026-04-24

#Added

• KitTools commit signing — Commits created by KitTools agents during orchestration now include a Co-Authored-By: KitTools + Claude trailer, making it easy to identify KitTools-originated commits in your git history.

---

#2.4.1 — 2026-04-24

#Fixed

• Dirty-tree self-block on resume — The orchestrator writes a run header to EXECUTION_LOG.md after the clean-worktree check passes, but before story execution begins. If the orchestrator then crashes, the log is left dirty and every subsequent relaunch fails. Fixed by committing the log header immediately after writing it, closing the dirty-tree window.

#Added

• Hybrid model escalation — New escalation model role (defaults to Opus). On retry for specs marked size: L or size: XL, the implementation session upgrades from Sonnet to the escalation model. First attempt is always Sonnet — cheap exploration that produces learnings. Retry gets Opus for stories where the context is too large for Sonnet to process within the timeout.
• size: frontmatter field — Feature specs can now declare size: S | M | L | XL to control session timeouts and model escalation on retry.

#Changed

• Story sizing raised to 5–7 criteria — Sweet spot raised from 3–5 to 5–7 acceptance criteria per story. The old 3–5 range caused planners to drop criteria to fit, producing under-specified stories. The new guidance: more stories with well-defined criteria is always better than fewer stories with compressed scope.
• Story-quality-reviewer hard ceilings — Two new critical (execution-blocking) triggers: more than 10 acceptance criteria, or spanning 3+ architectural layers. Previously all oversized stories were warnings, meaning they could proceed to execution and time out.
• Plan-epic sizing step — The final scope check now includes guidance for setting size: frontmatter based on spec complexity.

---

#2.4.0 — 2026-04-17

Foundation refactor. 2.4.0 is a deep audit of the plugin: hardening, architectural cleanup, cross-agent consistency, and a full decomposition of the orchestrator. The user-visible workflow is unchanged — every skill you invoke still behaves the same — but the internals are substantially more robust and easier to extend.

#Added

• Model configurability — Per-run model selection for orchestrator-spawned sessions. Defaults: Sonnet for implementation (cost-optimized for bulk generation), Opus for verification (quality gate), Opus for post-execution validation. Override per-run via a model_config block in the execution config, or pick a preset at launch via /kit-tools:execute-epic.
• Unified finding schema for review agents — Every review agent (code-quality-validator, security-reviewer, feature-compliance-reviewer, drift-detector, template-validator, and all spec/vision reviewers) now emits findings in one canonical JSON shape. Skills parse a single format instead of three text-block dialects, which makes adding new review dimensions a lot easier.
• Feature spec frontmatter schema doc — New templates/specs/SCHEMA.md documents every valid field on feature-*.md and epic-*.md files, with validation rules and examples for standalone, epic-child, and epic-final cases.
• Vision review split — The single vision-reviewer agent (which had three different modes baked into one prompt) is now three focused agents: vision-completionist-reviewer, vision-feasibility-reviewer, and vision-readiness-reviewer. Each has one clear job and one output shape.
• Structured event logging — Orchestrator now writes a machine-readable JSONL event log (kit_tools/.execution-events.jsonl) alongside the human-readable stdout stream. Instrumented at critical failure sites. Post-mortem debugging with jq just works now.
• EXECUTION_LOG.md rotation — The execution log now rotates past 5 MB, keeping one .1 backup. No more unbounded log growth across resumed runs.
• Clean-worktree precondition — The orchestrator now checks for a clean git worktree before creating any branches. If the tree is dirty or the directory isn’t a git repo, you get a clear error up front instead of a confusing failure deep in branch creation.
• Git recovery detection — When git merge --abort or git revert leaves the repo stuck in MERGING/REVERTING/CHERRY-PICKING/REBASING state, the orchestrator now detects it and escalates with specific remediation guidance rather than blindly retrying. Uses git rev-parse --git-dir so it works inside linked worktrees too.
• State schema versioning — .execution-state.json carries a schema_version field. Newer-than-supported state aborts with a clear message; older-than-current is tolerated (auto-upgraded on next save). Corruption and malformed state get caught at load-time instead of crashing downstream.

#Changed

• Orchestrator decomposition — The single 4,087-line execute_orchestrator.py is now a 13-module package (utils, events, config, state, specs, prompts, sessions, tests_metrics, git_ops, supervisor, execution_log, executor, entry). The CLI entry point remains execute_orchestrator.py as a thin shim — no skill changes, no workflow changes.
• Explicit tool grants on all agents — Every agent declares exactly which tools it’s allowed to use. Review agents can’t Edit source. Story-verifier can’t modify code. The “independent verifier” boundary is now enforced at the tool layer, not just prompt-layer.
• Atomic state writes — State, health snapshots, test metrics, and control files now write via temp-file + fsync + atomic rename. Mid-write crashes no longer corrupt state. The supervisor polling .execution-health.json never sees a partial file.
• spec-second-opinion model unpinned — The cross-model second-opinion reviewer no longer hardcodes Sonnet. The invoking skill picks a secondary model at invocation time (different from the primary), so the pattern keeps working as new models ship without needing to re-author the agent.
• Supervisor cron cleanup extended — 2.3.1’s self-cleanup handled Completed and “no execution state” cases. 2.4.0 extends to Crashed, Stale, and Failed states, so a supervisor cron never lingers past a run that stopped making progress. /kit-tools:execute-epic docs now explicitly surface the cron’s lifetime (tied to the OG session) and the laptop-sleep caveat.
• /kit-tools:sync-project description sharpened — Description now leads with outcome instead of jargon. New “When to use” and “Outcome” sections make the quick / full / resume modes easier to choose between.
• Prompt-injection hygiene — Nine code-reading agents (story-implementer, story-verifier, the validation reviewers, drift-detector, test-optimizer, generic-explorer, feature-fixer) got an explicit callout that code, comments, and tool output they consume may contain adversarial prompt-injection attempts and should be treated as text to analyze, never as instructions to execute.

#Fixed

• Orchestrator hang after SIGKILL — proc.wait() after killing a subprocess had no timeout. If SIGKILL didn’t take (zombie, permissions, uninterruptible sleep), the orchestrator could hang indefinitely. Now bounded at 10 seconds — prefers a leaked PID over a stuck 24-hour autonomous run.
• Stuck merge/revert recovery — Previously, a failed git merge --abort or git revert --abort would be logged as a warning and immediately retried, which would also fail. Now each abort is checked for stuck state and raises with manual-remediation guidance.
• Worktree indirection for git recovery — Previously, the merge/revert state check looked at project_dir/.git/MERGE_HEAD directly, which fails in linked worktrees where .git is a file pointing elsewhere. Now uses git rev-parse --git-dir to follow the indirection correctly.
• Prompt substitution drift guard — If a prompt builder typo’d a token name (e.g., {{STORRY_ID}}), the malformed {{...}} marker would silently survive into the agent’s prompt. Now every built prompt is checked for leftover tokens and raises with a specific error pointing at the typo.

#Removed

• /kit-tools:sync-symlinks — Claude 3.5-era workaround for stale autocomplete symlinks. The plugin’s skill discovery works correctly without it now.
• /kit-tools:update-kit-tools — The standard /plugin update kit-tools@washingbearlabs does the same thing natively. To add templates or hooks that weren’t initially selected in your project, re-run /kit-tools:init-project and choose the merge option.

---

#2.3.1 — 2026-04-10

#Fixed

• Supervisor cron cleanup — The supervisor monitoring cron job now self-cleans when execution completes. Previously, the cron created by /kit-tools:execute-epic kept polling after the orchestrator finished and cleaned up its state files. Now /kit-tools:execution-status detects there’s nothing to monitor and deletes its own cron job.

---

#2.3.0 — 2026-04-06

#Added

• Supervisor monitoring mode — New --monitor option for autonomous and guarded execution. When enabled, the launching Claude session stays active as a supervisor, checking orchestrator health every 30 minutes. The supervisor can detect crashes, split oversized stories, pause on repeated failures, and restart the orchestrator — all without requiring system-level permissions (communication happens through JSON files, not shell commands).
• Story splitting — The supervisor can split stories that repeatedly fail due to scope. It writes full replacement story definitions (with proper US-NNN IDs) to a control file, and the orchestrator applies the split to the feature spec automatically.
• Graduated intervention — The supervisor follows an escalation path: observe retries → intervene after exhaustion → escalate to user if intervention fails. Prevents both premature intervention and runaway failure loops.
• 24-hour safety net — Orchestrator self-terminates after 24 hours with a critical notification.
• Health snapshots — Orchestrator writes health data (heartbeat, memory, PIDs, failure counts) after every story attempt. The supervisor reads these to assess health without running system commands.
• Test metrics tracking — New kit_tools/testing/test-metrics.json tracks per-file test pass/fail counts, durations, timeouts, and last run dates across orchestration runs. Portable JSON — no external dependencies.
• Verifier: tests_run result field — The verifier now reports which test files it executed, their pass/fail status, and duration. Feeds into test metrics for identifying slow or flaky tests.

#Fixed

• Orchestrator: orphaned process cleanup — Claude sessions now kill their entire process group on normal exit, not just on timeout. Previously, child processes (pytest, vitest, node workers) spawned during sessions survived after the session completed, accumulating across stories in an epic and eventually exhausting system memory.
• Orchestrator: regression check process handling — Regression tests now run with proper process group isolation. Timeouts kill pytest and all its children instead of only the wrapper shell.
• Orchestrator: graceful process termination — Process groups are now terminated with SIGTERM first (with a grace period) before SIGKILL, allowing child processes to clean up.
• Orchestrator: tmux cleanup timeout — kill_tmux_session now has a timeout to prevent hanging if tmux is unresponsive.

#Changed

• Verifier: no more full-suite fallback — When targeted test detection finds no matches, the verifier now identifies and runs only relevant tests from the diff instead of falling back to the full test suite. Prevents multi-minute test runs in large codebases. Broader coverage is still enforced by the regression check and end-of-epic validation.

---

#2.2.2 — 2026-04-04

#Added

• New Skill: /kit-tools:optimize-tests — Full test suite audit covering mapping completeness, stale test detection, coverage overlap, performance profiling, KitTools convention alignment, and suite verification. Run periodically to keep your test suite healthy as the codebase grows.
• Orchestrator: intelligent retry system — Failed stories now receive structured retry context based on failure type (timeout, test failure, criteria mismatch). The orchestrator classifies failures automatically and tailors guidance for each retry attempt.
• Orchestrator: adaptive timeouts — Implementation and verification sessions use separate timeout budgets (900s/600s). Optional size: S/M/L/XL in spec frontmatter scales timeouts for larger stories.
• Orchestrator: pre-flight checks — Before each story, the orchestrator checks for oversized scope and test mapping gaps. Warnings are logged but don’t block execution.
• Orchestrator: cross-story regression detection — After merging a story, the orchestrator runs prior stories’ tests to catch regressions. If a regression is detected, the merge is reverted and execution halts with a notification.
• Orchestrator: learnings persistence — Execution learnings now persist across epics in a JSONL file. Future runs benefit from lessons learned in prior epics.
• Verifier: pass-with-warnings verdict — The verifier can now return a third verdict for non-blocking concerns (style, naming). Stories merge immediately; warnings accumulate for review during validation.

#Changed

• Orchestrator: smarter test targeting — Complete rewrite of test detection with tiered matching (T0: explicit mapping, T1: heuristic). Directory-scoped matching preferred over global search. Match caps prevent timeout-causing over-matching.
• Completionist reviewer — New “Integration & Wiring Completeness” dimension checks for UI gaps, unwired artifacts, missing cross-layer connections, and scope narrowness.
• Story quality reviewer — New anti-pattern detection (vague verbs, compound criteria) and story ordering checks.

---

#2.2.1 — 2026-04-03

#Changed

• /kit-tools:validate-feature → /kit-tools:validate-implementation — Renamed to better reflect that this skill validates the implementation (code on a branch), not the feature spec itself. No behavioral changes.
• /kit-tools:complete-feature → /kit-tools:complete-implementation — Renamed for consistency with the epic-forward workflow. No behavioral changes.
• All cross-references updated across skills, agents, hooks, orchestrator, templates, and documentation.

---

#2.2.0 — 2026-04-01

#Added

• Pre-execution validation (/kit-tools:validate-epic) — Quality gate between planning and execution. Runs four sequential agent reviews on every feature spec in an epic before coding starts:

  1. Completionist reviewer — Missing stories, uncovered goals, flow gaps
  2. Story quality reviewer — Story sizing, ID format, vague criteria, integration scope
  3. Salty engineer reviewer — Adversarial GAN-style review for implementation traps, hand-waving, and deployment risks
  4. Second opinion (Sonnet) — Cross-model review using a different AI model to evaluate architecture decisions, feasibility, over-engineering, and alternative approaches. All alternatives require explicit trade-off statements.
  • Interactive: revise specs and re-run reviews between agents. Produces a go/no-go readiness verdict.

• Epic-first planning (/kit-tools:plan-epic) — All work is now structured as an epic, even single-spec features. Replaces the old binary “epic detection” gate with a scope assessment that determines how many feature specs are needed. Always generates an epic-*.md wrapper alongside feature specs.

• Desktop notifications for autonomous execution — The orchestrator now sends OS-level notifications (macOS and Linux) on story failures, execution completion, crashes, and pauses. No more discovering failures hours after they happen.

• READ_ME.html — Single-file HTML5 documentation page with an interactive 8-phase workflow flowchart, skills grid, hooks table, and install guide.

#Changed

• /kit-tools:execute-epic (formerly execute-feature) — Epic-first entry point: selects the epic from epic-*.md files, derives execution order from the Decomposition table.
• /kit-tools:complete-implementation — Enhanced learnings capture: gotchas go to GOTCHAS.md, conventions to CONVENTIONS.md, spec-writing notes to Implementation Notes. Context-aware next steps guide to the next epic or feature.
• Workflow handoffs improved — seed-project, start-session, and complete-implementation now include clear next-step guidance, closing the workflow loop from init through completion and back to planning.
• Repositioned from “documentation framework” to “framework for AI-assisted development” — Updated across all repos and documentation.

#Removed

• /kit-tools:plan-feature — Replaced by /kit-tools:plan-epic
• /kit-tools:execute-feature — Replaced by /kit-tools:execute-epic
• /kit-tools:migrate — v1.x → v2.0 migration no longer supported as a dedicated skill

---

#2.1.4 — 2026-03-18

#Fixed

• Orphaned subprocess cleanup on timeout — Timed-out execution sessions now kill the entire process group (claude + all child processes like pytest, node, etc.) instead of just the direct child. Previously, orphaned test runners would accumulate and consume CPU indefinitely after session timeouts.

---

#2.1.3 — 2026-03-13

#Changed

• Smart test scoping — Story verification now runs only related tests instead of the full suite. Tests are matched by naming convention (e.g., foo.py → test_foo.py) or explicit test mappings in your project’s TESTING_GUIDE.md. The full suite runs only at the validate-implementation gate.
• Test output control — Quiet flags suppress per-test PASSED noise while preserving full failure tracebacks and assertion diffs. A safety-net output cap prevents runaway output without hiding failure details.

---

#2.1.2 — 2026-03-11

#Added

• Inline diff for verifier — The verifier agent now receives the full diff content inline (up to 20KB) instead of reading files one-by-one via tool calls. Large diffs are truncated with a stat summary and the verifier falls back to reading full files.
• Fail-fast test flags — Verification test commands now include fail-fast flags for known runners (pytest -x, jest --bail, vitest --bail 1), stopping at the first failure instead of running the full suite. The full suite is preserved for validate-implementation.
• Completion strategy — Choose how execution finishes with a new completion_strategy option:
  • Create PR (default) — Pushes branch and creates a GitHub PR via gh
  • Merge to main — Auto-merges to main (blocked if validation finds critical issues, falls back to PR)
  • None — Leaves branch as-is for manual handling
  • The orchestrator now handles completion directly instead of spawning a separate Claude session

#Changed

• Verifier diff accuracy — Diffs use explicit commit-based two-dot syntax instead of merge-base, eliminating ambiguity in multi-commit scenarios
• Verifier workflow — Review step updated to start from the inline diff, using the Read tool only when more context is needed
• Epic completion — Epics now complete via the same completion strategy instead of spawning a separate completion session
• /kit-tools:execute-feature — New Step 2b prompts for completion strategy; pre-flight checks verify gh auth when PR strategy is selected

---

#2.1.1 — 2026-03-07

#Fixed

• Epic automation state mismatch — Fixed a crash when running epic execution in autonomous mode. The skill was pre-creating state with the wrong schema; now the orchestrator handles state creation for both single-spec and epic modes.
• Orchestrator crash resilience — Crash handler now registers before config load; leaked attempt branches are cleaned up on startup; archive operations are atomic (write-then-delete instead of modify-then-move)
• Agent output parsing — Orchestrator now handles common LLM output quirks: markdown code fences around JSON, preamble text, and trailing commas
• Verification session errors — Session errors are now checked before reading result files, preventing stale result reads
• Scratchpad hook feedback — Scratchpad creation failures are now reported instead of silently swallowed
• Placeholder validation accuracy — Tightened patterns to stop flagging legitimate markdown like [note] or [example] as unfilled placeholders
• Manifest completeness — Added missing templates to both SEED_MANIFEST and SYNC_MANIFEST

#Changed

• Execute feature skill — State initialization now defers to the orchestrator for autonomous/guarded modes, preventing schema mismatches
• Execution status skill — Token estimate display handles missing data gracefully
• Story quality pre-flight — Execute-feature now checks story quality before launching (flags vague criteria, under-specified stories)
• Learnings cap — Per-story learnings capped at 20 at write time to prevent state file bloat
• Template versions — All 30 templates normalized to version 2.0.0
• Network retry clarity — Rewrote session retry logic for clearer error categorization
• Dead code cleanup — Removed unused functions and imports from orchestrator

---

#2.1.0 — 2025-03-04

#Added

• New Skill: /kit-tools:create-vision — Interactive product vision definition with AI-assisted review
  • Guided conversation captures your vision, target users, value proposition, success criteria, and feature areas
  • Two-pass review: completeness scoring across 6 dimensions, then feasibility assessment
  • Surfaces gaps and suggestions between rounds for iterative refinement
  • Produces kit_tools/PRODUCT_VISION.md — one strategic document per project
• New Template: PRODUCT_VISION.md — Singular root-level strategic document replacing Product Briefs
  • Sections: Vision Statement, Target Users & Personas, Value Proposition, Success Criteria, High-Level Feature Areas, Constraints & Assumptions, Open Questions

#Changed

• /kit-tools:plan-feature — Now checks for Product Vision instead of Product Briefs
  • Reads vision doc for strategic context when planning features
  • Step 12 updates both BACKLOG.md and MILESTONES.md with priority confirmation
  • Feature specs use vision_ref: instead of brief: frontmatter
• /kit-tools:init-project — Recommended workflow updated: init → seed → create-vision → plan-feature
• /kit-tools:migrate — New vision/brief migration steps: creates blank vision doc if missing, flags legacy briefs for review, checks v2.0 completeness
• Feature Spec and Epic templates — brief: field replaced with vision_ref: (references a section in PRODUCT_VISION.md)

#Removed

• Product Brief template (PRODUCT_BRIEF.md) — Replaced by Product Vision

---

#2.0.0 — 2026-03-01

#Breaking Changes

• kit_tools/prd/ → kit_tools/specs/ — The feature specs directory has been renamed. All internal paths, config keys, state keys, and agent tokens updated to match.
  • Run /kit-tools:migrate to update existing projects automatically
  • Config keys renamed: prd_path → spec_path, epic_prds → epic_specs
  • State keys renamed: prd → spec, prds → specs, current_prd → current_spec

#Changed

• /kit-tools:migrate rewritten — Now handles v1.x → v2.0 migration: directory rename, file renames (prd-*.md → feature-*.md), config/state key migration, hook path updates, and documentation path sweep. All steps are idempotent — safe to run multiple times.
• Backwards compatibility preserved — detect_phase_completion hook checks both kit_tools/specs/ and kit_tools/prd/ paths. Archive dependency lookups check both feature-*.md and prd-*.md patterns.

---

#1.6.6 — 2026-03-01

#Added

• PRD Compliance Agent — PRD compliance review is now a dedicated subagent (prd-compliance-reviewer) that runs in parallel with code quality and security reviews during feature validation. Previously this ran inline in the validation session, consuming context window.
• Diff summarization — Large branch diffs are automatically truncated per-file (60KB budget) before being passed to validator agents. Agents are instructed to read full files when they need more context.
• Prompt size guard — Implementation and verification prompts are automatically trimmed if they approach context limits (480K chars). Removes prior learnings and previous attempt diffs first, with a hard-truncate fallback.
• Result schema validation — Agent result files are now validated on read. Missing required fields (like story_id, status, verdict) return clear errors instead of causing cryptic failures downstream.

#Fixed

• Permanent error handling — Context window and token limit errors are now classified as permanent and cause immediate failure with notification, instead of retrying indefinitely
• PRD checkbox scoping — Checkbox replacement now uses regex with line-start anchoring, preventing false positives when - [ ] appears inside descriptions or hint text
• Git operation visibility — All git operations now log warnings on failure instead of silently ignoring errors
• Pause timeout — Paused execution now auto-resumes after 24 hours with periodic log reminders, preventing indefinite hangs

#Changed

• Parallel validation — Feature validation Steps 3 (quality), 4 (security), and 5 (compliance) can now all run in parallel as independent subagents

---

#1.6.5 — 2026-02-26

#Fixed

• Nested session errors — The orchestrator now strips the CLAUDECODE environment variable before spawning claude -p subprocesses, eliminating the “cannot be launched inside another Claude Code session” error in autonomous/guarded mode
• Cleanup on error exits — All orchestrator exit paths (Ctrl+C, max retries, dependency failures, crashes) now properly clean up tmux sessions, commit tracking files, and remove temporary result files
• Merge conflict handling — If merging an attempt branch into the feature branch fails, the orchestrator now aborts the merge and retries instead of silently marking the story as completed
• Result file cleanup — Temporary result files are now cleaned on all retry paths, preventing stale data from being misread on restart
• Hook robustness — All hooks now wrap file I/O in error handling to prevent tracebacks on encoding errors or permission issues

#Changed

• Notifications simplified — Removed macOS native notifications (osascript). All execution progress is now reported through in-session notifications surfaced on your next prompt. No more context-switching to Notification Center.
• tmux self-cleanup — The orchestrator now kills its own tmux session on completion. No more orphaned sessions lingering after execution finishes.

#Added

• Git health check — /kit-tools:start-session now checks branch state, uncommitted changes, stash, remote sync status, and recent commits before orienting. Issues are flagged with suggestions, but no actions are taken without your approval.
• Plugin discoverability — Projects using KitTools now include an install hint in SYNOPSIS.md so new contributors can find and install the plugin.

---

#1.6.4 — 2026-02-23

#Added

• Execution Notification System — Two-pronged notifications keep you informed during autonomous/guarded execution
  • macOS native alerts fire immediately on completions, failures, crashes, and pauses — no need to check manually
  • In-session notifications via a UserPromptSubmit hook surface a batched summary the next time you send a message to Claude
  • Nine notification points cover the full execution lifecycle: story pass, story failure, single-PRD complete, validation pause, epic PRD complete, between-PRD pause, all epic PRDs complete, dependency blocked, and crash
  • Crash detection — An atexit handler detects unexpected orchestrator exits, sets state to crashed, and sends both an OS alert and a file notification
• Crashed status in execution-status — /kit-tools:execution-status now recognizes the crashed state with resume/reset actions (same options as stale state)

#Changed

• Distribution cleanup — Test files and dev dependencies removed from the shipped plugin. Only runtime files are included in installs.

---

#1.6.3 — 2026-02-23

#Fixed

• Unique tmux session names — Autonomous execution now uses descriptive, per-feature session names (kit-exec-{feature}) instead of a single hardcoded name
  • Running multiple projects concurrently no longer risks killing each other’s tmux sessions
  • Session names are stored in the execution config so /kit-tools:execution-status can find the right session
  • Backwards compatible with older runs

---

#1.6.2 — 2026-02-23

#Added

• New Skill: /kit-tools:execution-status — Check progress of autonomous execution from within Claude Code
  • Shows completion percentage, per-story status table, session stats (tokens, time elapsed)
  • Detects stale state when the orchestrator has crashed or exited
  • Offers contextual actions based on current state: pause, resume, attach to tmux, retry
  • Epic mode: shows per-PRD progress table

---

#1.6.1 — 2026-02-23

#Fixed

• Autonomous execution launch — The orchestrator now launches in a detached tmux session instead of running in the background from within a Claude session
  • Fixes nested claude -p calls being blocked by Claude Code’s recursion prevention
  • If tmux is not installed, a copy-pasteable command is printed for running in a separate terminal
  • Pre-flight checks now verify tmux availability for autonomous/guarded modes
  • Monitoring commands (attach, tail log, check state, pause) reported after launch

---

#1.6.0 — 2026-02-22

#Added

• Unit Test Suite — 75 tests for the execute orchestrator covering PRD parsing, story extraction, prompt building, and test command detection
• File-Based Agent Results — Agents write structured JSON result files (.story-impl-result.json, .story-verify-result.json) instead of stdout parsing, eliminating ~33% false failure rate from LLM output formatting
• Branch-per-Attempt Strategy — Each implementation attempt runs on a temporary branch; successful attempts merge, failed attempts are deleted cleanly (no more destructive git reset)
• Patch-Based Retry Context — Failed attempt diffs are included in retry prompts so the agent takes a different approach
• Token Estimation — Per-session input/output token tracking logged in execution state
• Auto-Detect Test Command — Automatically finds the project’s test runner by checking package.json, pyproject.toml, pytest.ini, Makefile, and TESTING_GUIDE.md
• Test Execution in Validation — /kit-tools:validate-implementation now runs the project’s test suite; failed tests are logged as critical findings
• Auto-Injected Test Criteria — /kit-tools:plan-feature automatically adds “Tests written/updated” and “Full test suite passes” criteria to every code story (doc/config-only stories are exempt)
• Implementation Hints — Per-story hints flow from planning to implementation, reducing agent exploration time
  • plan-feature generates hints during refinement (key files, patterns, gotchas)
  • Implementer agent receives hints as part of its prompt
• Pause on Critical Findings — Autonomous execution pauses when validation finds critical issues, creating a .pause_execution file referencing the findings. Resumes when the file is removed after review.

#Changed

• YAML Parsing — Replaced hand-rolled frontmatter parser with PyYAML for proper handling of lists, booleans, and edge cases
• Verifier Independence — Verifier agent receives git-sourced file lists (git diff --name-only) instead of trusting implementer claims
• Reference-Based Context — Agent prompts pass file paths instead of inlining full contents, reducing prompt size ~80% for large projects
• Skill Structure — Four pipeline skills (execute-feature, plan-feature, validate-implementation, complete-implementation) split into SKILL.md (core workflow) + REFERENCE.md (detailed formats and examples), reducing context consumption significantly
• PRD Template — Updated to v1.3.0 with Implementation Hints section and auto-injected test criteria

#Deprecated

• Stdout-based result parsing — Kept for backward compatibility but superseded by file-based JSON results
• reset_to_commit() — Replaced by branch-per-attempt strategy

---

#1.5.4 — 2026-02-19

#Fixed

• Hook path resolution — Project-level hook commands now use $CLAUDE_PROJECT_DIR instead of relative paths
  • Previously, hooks used python3 kit_tools/hooks/... which breaks if shell CWD drifts during a session
  • Now uses python3 "$CLAUDE_PROJECT_DIR/kit_tools/hooks/..." — resolves correctly regardless of CWD
  • Fixes an infinite loop scenario where a Stop hook file-not-found error re-triggers the Stop event
  • Existing projects: run /kit-tools:update-kit-tools to get the updated hook paths

---

#1.5.3 — 2026-02-09

#Added

• Epic Chaining — Multi-PRD epics now execute automatically on a shared epic/[name] branch
  • PRD template gains epic, epic_seq, epic_final frontmatter fields
  • /kit-tools:execute-feature detects epic PRDs and offers sequential execution
  • Orchestrator chains PRDs: stories -> validate -> tag checkpoint -> archive -> next PRD
  • Hard dependency gate blocks execution if depends_on PRDs aren’t archived
  • Git tags mark each PRD checkpoint (e.g., oauth/oauth-schema-complete)
  • Resume support: skips already-completed PRDs on restart
  • Cross-PRD learnings carried forward to subsequent story prompts
• Pause Between PRDs — Option to review after each PRD before continuing the epic
  • Recommended default for epic execution
• Epic-Aware Completion — /kit-tools:complete-implementation handles mid-epic and final-epic PRDs
  • Mid-epic: tag + archive only (no PR or artifact cleanup)
  • Final epic PRD: PR references all PRDs and checkpoint tags

#Fixed

• Verifier output parsing — Strips markdown code fences before parsing, fixing ~33% false failure rate when the verifier wraps output in triple backticks
  • Fallback verdict detection scans for pass/fail signals when the structured block is missing
  • Raw output logged on parse failure for diagnosis
• Verification-only retry — When implementation succeeded but verifier parsing failed, retries now skip re-implementation and only re-run verification
• Failure detail sanitization — Log entries no longer contain raw template content from session errors
• Verifier template — Now explicitly instructs the LLM to output the structured block as plain text, not inside code fences

#Changed

• Orchestrator — Refactored into run_single_prd() and run_epic() with shared story execution loop
• /kit-tools:plan-feature — Epic decomposition now sets chaining fields (epic, epic_seq, epic_final)
• /kit-tools:execute-feature — Epic detection, dependency hard gate, epic/[name] branching, epic_prds config format

---

#1.5.2 — 2026-02-07

#Added

• New Skill: /kit-tools:validate-implementation — Full branch-level validation against PRD
  • Reviews entire branch diff (git diff main...HEAD) — all changes across the feature
  • Three independent review passes: code quality, security, and PRD compliance
  • Automatic fix loop (max 3 iterations) for critical findings
  • Autonomous mode: spawns a fixer agent; supervised mode: fixes inline
• Dedicated Security Review Agent — Security gets focused attention in its own review pass
  • Covers injection vulns, auth gaps, secrets, input validation, insecure defaults, dependency risks
• Dedicated Fix Agent — Targeted fixes for validation findings in autonomous mode
• Automatic validation after execution — The orchestrator now spawns a validation session after all stories complete

#Changed

• Code quality validator — Narrowed to quality-only (security and intent alignment moved to dedicated agents)
• /kit-tools:execute-feature — Completion messaging now directs to validate-implementation
• /kit-tools:complete-implementation — Now cleans up execution artifacts, handles feature branch (PR/merge), and references validate-implementation
• /kit-tools:close-session and /kit-tools:checkpoint — Use inline quality checks for session-level diffs instead of the full feature validation
• detect_phase_completion hook — Only suggests validate-implementation when all PRD criteria are complete, not on every checkbox

#Removed

• /kit-tools:validate-phase — Replaced by validate-implementation (branch-level validation)

---

#1.5.1 — 2026-02-06

#Added

• New Skill: /kit-tools:sync-symlinks — Force-refresh skill symlinks after a plugin update
  • Reads installed_plugins.json to find the correct install path
  • Useful when skills appear stale after /plugin update

#Fixed

• sync_skill_symlinks hook — Now reads ~/.claude/plugins/installed_plugins.json as the source of truth for the plugin install path
  • Fixes issue where skill symlinks remained pointed at the previous version after a plugin update
  • $CLAUDE_PLUGIN_ROOT can be stale after updates; the hook now bypasses it in favor of the authoritative JSON

---

#1.5.0 — 2026-02-06

#Added

• Native Autonomous Execution — /kit-tools:execute-feature replaces the previous Ralph integration
  • Three execution modes: Supervised, Autonomous, and Guarded
  • Supervised: in-session with user review between stories
  • Autonomous: spawns independent claude -p sessions per story (unlimited retries by default)
  • Guarded: autonomous with human oversight on failures (3 retries default)
• Story Implementer Agent — agents/story-implementer.md implements a single user story
  • Explores codebase, implements changes, self-verifies, commits
  • Structured output format for orchestrator parsing
• Story Verifier Agent — agents/story-verifier.md independently verifies acceptance criteria
  • Skeptical assessment — reads actual code, doesn’t trust implementer claims
  • Runs typecheck/lint/tests as specified in criteria
• Execution Orchestrator — scripts/execute_orchestrator.py manages multi-session execution
  • Spawns fresh Claude sessions per story (implementation + verification)
  • Pause/resume via touch kit_tools/.pause_execution
  • Dual-track state: PRD checkboxes + JSON sidecar
  • Execution log at kit_tools/EXECUTION_LOG.md
• Git Branch Isolation — All execution happens on feature/[prd-name] branches
  • Failed retries reset working tree, never touch main
  • Branch ready for user review when all stories complete

#Changed

• PRD Template — ralph_ready field renamed to session_ready
• /kit-tools:plan-feature — Removed Ralph references, uses session_ready and execute-feature
• /kit-tools:complete-implementation — Removed Ralph cleanup step, updated Related Skills

#Removed

• /kit-tools:export-ralph — Replaced by native execute-feature
• /kit-tools:import-learnings — Learnings captured natively during execution

---

#1.4.0 — 2025-02-02

#Added

• Epic Detection & Decomposition — /kit-tools:plan-feature now detects large features and decomposes them
  • Automatic detection of epic-sized scope (>7 stories, multiple subsystems, scope keywords)
  • Proposes breakdown into multiple focused PRDs
  • Tracks dependencies between related PRDs with depends_on field
• Ralph-Ready Validation — /kit-tools:export-ralph validates PRD scope before export
  • Checks story count (target <=7), acceptance criteria count (target <=35)
  • Soft warning with strong recommendation if PRD exceeds limits
  • Suggests decomposition via plan-feature if PRD is too large
• Senior Dev Persona — Skills now act as senior dev reviewers
  • Push back on scope creep and poorly-scoped PRDs
  • Ensure PRDs are set up for implementation success

#Changed

• PRD Template — Updated to v1.1.0 with new frontmatter fields
  • ralph_ready: true/false — Indicates if PRD is properly scoped
  • depends_on: [] — Array of feature names this PRD depends on
  • Added session-fit guidelines in template comments
• /kit-tools:plan-feature — Enhanced with scope validation
  • Final scope check before generating PRD
  • Story count limits (5-7 ideal, 8+ triggers warning)
  • Acceptance criteria limits (3-5 per story, <=35 total)

---

#1.3.0 — 2025-02-01

#Added

• PRD (Product Requirements Document) System — New workflow for feature planning
  • kit_tools/prd/ directory for PRD files with YAML frontmatter
  • kit_tools/prd/archive/ for completed PRDs
  • PRD template with user stories (US-XXX), acceptance criteria, functional requirements (FR-X)
• New Skill: /kit-tools:complete-implementation — Mark PRD as completed and archive it
• New Skill: /kit-tools:export-ralph — Convert KitTools PRD to ralph’s prd.json format
• New Skill: /kit-tools:import-learnings — Import ralph progress.txt learnings back to PRD

#Changed

• /kit-tools:plan-feature — Now generates PRDs (prd-[name].md) instead of FEATURE_TODO_*.md
  • User story format with acceptance criteria
  • Functional requirements in FR-X format
  • Implementation Notes section for capturing learnings
• /kit-tools:start-session — Now checks kit_tools/prd/ for active features
• /kit-tools:close-session — Prompts for Implementation Notes when working on a PRD
• /kit-tools:checkpoint — Captures learnings to active PRD’s Implementation Notes

---

#1.1.0 — 2025-01-28

#Added

• New Skill: /kit-tools:validate-phase — Code quality, security, and intent alignment validation
  • Three-pass review: quality & conventions, security, intent alignment
  • Findings written to persistent AUDIT_FINDINGS.md with unique IDs and severity tracking
• New Agent: code-quality-validator.md — Prompt template for the validation subagent
• New Template: AUDIT_FINDINGS.md — Persistent audit findings log
  • Status tracking (open / resolved / dismissed)
  • Severity levels (critical / warning / info)
• New Hook: detect_phase_completion — Advisory hook for TODO task completions

#Changed

• /kit-tools:checkpoint — Added validation step for code changes
• /kit-tools:close-session — Added validation step
• /kit-tools:start-session — Reviews open audit findings

---

#1.0.0 — 2025-01-27

#Added

• Initial public release
• Core Skills: init-project, seed-project, migrate, start-session, close-session, checkpoint, plan-feature, sync-project, update-kit-tools
• Automation Hooks: create_scratchpad, update_doc_timestamps, remind_scratchpad_before_compact, remind_close_session
• Project Type Presets: API/Backend, Web App, Full Stack, CLI Tool, Library, Mobile, Custom
• 25+ Documentation Templates across Core, API, Ops, UI, and Patterns categories

---

GitHub Repository