worclaude 2.2.5 → 2.3.0

package/CHANGELOG.md

@@ -0,0 +1,97 @@
+# Changelog
+
+All notable changes to worclaude are documented in this file. Format loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow [semver](https://semver.org/). Older releases (pre-2.3.0) are documented in [docs/spec/PROGRESS.md](./docs/spec/PROGRESS.md) and the [GitHub releases page](https://github.com/sefaertunc/Worclaude/releases).
+
+## [2.3.0] — 2026-04-15
+
+Worclaude 2.3.0 expands the workflow from a setup scaffold into a full **learning system**: Claude captures corrections automatically, replays them across sessions, and now generates cross-tool rule files so switching from Claude Code to Cursor or Codex does not mean re-writing your conventions. Eight lifecycle hooks (up from three) plus a dedicated `coding-principles` reference card tighten the feedback loop between you and Claude.
+
+### Learning loop: capture once, replay everywhere
+
+- New `/learn <rule>` slash command writes rules to `.claude/learnings/{category}.md` with structured YAML frontmatter. Trigger phrases (`remember this`, `learn this`, `save this rule`) also invoke it.
+- New `correction-detect.cjs` hook (UserPromptSubmit) watches for correction signals in your prompts — "no, that's wrong", "you forgot", "actually, …" — and surfaces a suggestion to capture the correction as a `[LEARN]` block.
+- New `learn-capture.cjs` hook (Stop) scans the session transcript for `[LEARN]` blocks and persists them automatically, updating `.claude/learnings/index.json`.
+- SessionStart hook now reloads the most recent learnings on every session start, so rules you captured last week are already in context when you open Claude today.
+- Learnings are gitignored by default — personal to the developer, not shared. Promote a learning into CLAUDE.md when it matures into a team-wide rule.
+
+### Hook lifecycle: 3 → 8 events
+
+- **PreCompact** — new emergency git snapshot to `.claude/sessions/` before auto-compaction, so context truncation never loses in-flight state.
+- **UserPromptSubmit** — correction detection (above) + skill-hint matcher that surfaces relevant installed skills based on token overlap with your prompt.
+- **Stop** — learning capture (above) and desktop notification.
+- **SessionEnd / Notification** — quiet-by-default session-end and tool-use alerts.
+- Existing `SessionStart`, `PostToolUse`, `PostCompact` hooks retained and enriched.
+
+### Cross-tool compatibility: AGENTS.md
+
+- `worclaude init` now writes `AGENTS.md` alongside `CLAUDE.md`. Cursor, OpenAI Codex, GitHub Copilot, and other tools read `AGENTS.md`; Claude Code reads `CLAUDE.md`. Both are generated from the same source, so switching tools does not require maintaining parallel rule files.
+- `worclaude upgrade` and `/sync` regenerate `AGENTS.md` when `CLAUDE.md` changes.
+- `worclaude doctor` verifies `AGENTS.md` exists and flags drift.
+
+### New universal skill: `coding-principles`
+
+- Karpathy-derived reference card covering four behavioral principles: **Think Before Coding** (state assumptions, surface ambiguity), **Simplicity First** (minimum code, no speculative abstractions), **Surgical Changes** (touch only what traces to the request), **Goal-Driven Execution** (define success criteria up front, close the feedback loop before committing).
+- Three new critical rules (10–12 in the scaffolded CLAUDE.md) enforce these principles at the always-loaded layer.
+
+### Agent enrichment (all 25 agents)
+
+Every agent template now includes:
+
+- **Confidence thresholds** for when to spawn vs defer
+- **Worked examples** showing input → output shape
+- **Verification depth levels** (quick check vs full audit)
+- **Severity classification** for findings
+- New frontmatter fields: `tools`, `effort`, `color`, `permissionMode`, `mcpServers`, per-agent `hooks`, `criticalSystemReminder`, `skills`, `initialPrompt`, `memory`.
+
+### Skill enrichment (all 12 universal skills)
+
+- **Must-Haves Contract** (planning-with-files) — lists non-negotiable elements of a good implementation plan.
+- **Gate Taxonomy** (verification) — classifies verification gates by cost and confidence.
+- **Context Budget Tiers** (context-management) — explicit budgets for main-session vs subagent context.
+- `version: "1.0.0"` frontmatter on all universal + template skills for future migration tracking.
+
+### Command enrichment (17 slash commands)
+
+- **Trigger phrases** — every command template declares natural-language triggers (e.g., `/learn` triggers on "remember this", "save this rule").
+- **`$ARGUMENTS` placeholders** — `/start`, `/end`, `/verify`, `/refactor-clean` now support explicit arguments.
+
+### Doctor improvements
+
+- **Hook-event validation** — flags invalid event names, deprecated events, and hook handlers referencing nonexistent scripts. `BLOCKING_BY_DESIGN_EVENTS` set correctly exempts events (SessionStart, PreToolUse, etc.) that must be blocking by design and should not be flagged as needing `async: true`.
+- **CLAUDE.md line budget check** — fails at the 200-line threshold so the always-loaded file stays lean.
+- **Deprecated-model check** — warns when agents reference models scheduled for retirement.
+- **Learnings integrity check** — validates `index.json` parses, referenced files exist, no orphans, frontmatter is well-formed.
+- **Gitignore coverage** — verifies `.claude/sessions/`, `.claude/learnings/`, and backup directories are properly ignored.
+
+### `plugin.json` generation (opt-in)
+
+- `worclaude init` can now write a Claude Code plugin manifest. Useful for publishing your scaffolded workflow as a shareable plugin.
+- Paired with `templates/hooks/README.md` and a `disableSkillShellExecution` awareness note on shell-heavy skill templates.
+
+### GTD memory scaffold (opt-in)
+
+- Optional structured-memory layer at `docs/memory/decisions.md` and `docs/memory/preferences.md` for teams that want a more explicit GTD-style capture than `.claude/learnings/` provides.
+
+### Other
+
+- Template version fields synced: all skill templates carry `version: "1.0.0"`.
+- `$ARGUMENTS` placeholder added to `/start`, `/end`, `/verify`, `/refactor-clean` templates so their argument descriptions match the actual runtime substitution.
+- 497 tests across 31 test files (up from 383 / 26).
+
+### Upgrade notes
+
+Upgrading from 2.2.x:
+
+```bash
+npm install -g worclaude@latest
+cd your-project
+worclaude upgrade
+```
+
+`worclaude upgrade` preserves your customizations via the partial-hash update fixed in 2.2.5. New templates (coding-principles skill, /learn command, four hook scripts, AGENTS.md) land automatically; files you modified stay untouched. Run `worclaude doctor` after upgrade to verify everything registered.
+
+If you have customizations to files that changed in 2.3.0, `upgrade` saves the new templates as `.workflow-ref.md` sidecars for manual reconciliation — see the [Upgrading guide](https://sefaertunc.github.io/Worclaude/guide/upgrading) for the reconciliation flow.
+
+### Breaking changes
+
+None. All 2.3.0 changes are additive.

package/README.md

@@ -1,100 +1,106 @@
-# Worclaude
+<p align="center">
+  <img src="assets/worclaude.png" alt="Worclaude — The Workflow Layer for Claude Code" width="100%" />
+</p>
 
-> One command. Best practices baked in. Your Claude Code environment, production-ready.
+<p align="center">
+  <a href="https://www.npmjs.com/package/worclaude"><img src="https://img.shields.io/npm/v/worclaude" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/worclaude"><img src="https://img.shields.io/npm/dm/worclaude" alt="downloads" /></a>
+  <a href="https://github.com/sefaertunc/Worclaude/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/sefaertunc/Worclaude/ci.yml?label=tests" alt="tests" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/sefaertunc/Worclaude" alt="license" /></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="node >= 18" />
+  <img src="https://img.shields.io/badge/built%20for-Claude%20Code-cc785c" alt="Built for Claude Code" />
+</p>
 
-[![npm version](https://img.shields.io/npm/v/worclaude.svg)](https://www.npmjs.com/package/worclaude)
-[![license](https://img.shields.io/npm/l/worclaude.svg)](LICENSE)
+<p align="center">
+  <a href="https://github.com/sponsors/sefaertunc"><img src="https://img.shields.io/badge/GitHub%20Sponsors-support-ea4aaa?logo=githubsponsors&style=for-the-badge" alt="GitHub Sponsors" height="40" /></a>
+  &nbsp;
+  <a href="https://buymeacoffee.com/sefaertunc"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-support-yellow?logo=buymeacoffee&style=for-the-badge" alt="Buy Me a Coffee" height="40" /></a>
+</p>
 
-<!-- GIF goes here once recorded -->
-<!-- ![worclaude init demo](docs/public/demo.gif) -->
+<p align="center">
+  <a href="https://sefaertunc.github.io/Worclaude/">Documentation</a> ·
+  <a href="https://www.npmjs.com/package/worclaude">npm</a> ·
+  <a href="https://github.com/sefaertunc/Worclaude/issues">Issues</a>
+</p>
 
-[Full Documentation](https://sefaertunc.github.io/Worclaude/) · [Interactive Demo](https://sefaertunc.github.io/Worclaude/demo/) · [npm](https://www.npmjs.com/package/worclaude)
+# Worclaude — The Workflow Layer for Claude Code
 
-Worclaude scaffolds a complete Claude Code workflow into any project in seconds. It implements all [tips by Boris Cherny](https://www.howborisusesclaudecode.com/) — the creator of Claude Code at Anthropic — as a reusable, upgradable scaffold. One `init` command gives you 25 agents, 16 slash commands, 15 skills, hooks, permissions, and a CLAUDE.md template tuned for your tech stack. Whether you're starting fresh or adding structure to an existing project, Worclaude handles the setup so you can focus on building.
+Worclaude scaffolds a complete Claude Code workflow into any project in seconds. One `init` command installs 25 agents, 17 slash commands, 16 skills, 8 lifecycle hooks, a two-store memory system, and a CLAUDE.md template tuned for your tech stack. It implements the patterns in [howborisusesclaudecode.com](https://www.howborisusesclaudecode.com/) as a reusable, upgradable scaffold, so you stop rebuilding the same configuration for every new project.
 
----
-
-## What You Get
+<div align="center">
 
-`worclaude init` installs a production-ready Claude Code workflow:
-
-**Agents (25 total)**
+| CLI Commands |          Agents           | Slash Commands |        Skills         |      Hooks       |  Tech Stacks  |
+| :----------: | :-----------------------: | :------------: | :-------------------: | :--------------: | :-----------: |
+|      8       | 5 universal + 20 optional |       17       |          16           |     8 events     |      16       |
+| subcommands  |    across 6 categories    | session tools  | universal + templates | lifecycle events | auto-detected |
 
-- 5 universal: plan-reviewer, code-simplifier, test-writer, build-validator, verify-app
-- 20 optional across 6 categories: Backend, Frontend, DevOps, Quality, Documentation, Data/AI
+</div>
 
-**Slash Commands (16)**
-`/start` `/end` `/commit-push-pr` `/review-plan` `/techdebt` `/verify` `/compact-safe` `/status` `/update-claude-md` `/setup` `/sync` `/conflict-resolver` `/review-changes` `/build-fix` `/refactor-clean` `/test-coverage`
+---
 
-**Skills (15)**
+## What You Get
 
-- 11 universal knowledge files (testing, git conventions, context management, security, coordinator mode, and more)
-- 3 project-specific templates filled in by `/setup`
-- 1 generated agent routing guide (dynamically built from your agent selection)
+`worclaude init` installs a production-ready Claude Code workflow:
 
-**Hooks**
+### Agents (25 total)
 
-- SessionStart context injection (auto-loads CLAUDE.md, PROGRESS.md, and last session on launch)
-- PostToolUse formatter (auto-formats on every write)
-- PostCompact re-injection (re-reads key files after compaction)
-- Stop notifications (desktop alert when Claude finishes)
-- Hook profiles (`WORCLAUDE_HOOK_PROFILE`) — minimal, standard, or strict
+- **5 universal:** plan-reviewer (Opus), code-simplifier (Sonnet, worktree), test-writer (Sonnet, worktree), build-validator (Haiku), verify-app (Sonnet, worktree)
+- **20 optional** across 6 categories — Backend, Frontend, DevOps, Quality, Documentation, Data/AI. Worclaude recommends agents based on your project type.
 
-**Configuration**
+### Slash Commands (17)
 
-- Pre-configured permissions per tech stack (Node.js, Python, Go, Rust, and more)
-- CLAUDE.md template with progressive disclosure
-- Sandbox, effort, and output defaults ready out of the box
+Session lifecycle, review, verification, memory, and git automation:
 
----
+`/start` `/end` `/commit-push-pr` `/review-plan` `/techdebt` `/verify` `/compact-safe` `/status` `/update-claude-md` `/learn` `/setup` `/sync` `/conflict-resolver` `/review-changes` `/build-fix` `/refactor-clean` `/test-coverage`
 
-## What's New in v2.x
+### Skills (16)
 
-The v2.x series introduced Claude Code runtime integration and continues to refine the workflow.
+- **12 universal** — context-management, git-conventions, planning-with-files, review-and-handoff, prompt-engineering, verification, testing, claude-md-maintenance, coding-principles, subagent-usage, security-checklist, coordinator-mode
+- **3 project templates** filled in automatically by `/setup` — backend-conventions, frontend-design-system, project-patterns
+- **1 generated** — agent-routing, dynamically built from your agent selections
 
-**Claude Code Runtime Integration**
+Skills use Claude Code's directory format (`skill-name/SKILL.md`) and support **conditional activation** via path globs, so Claude only carries knowledge relevant to the current file.
 
-- Skills use directory format (`skill-name/SKILL.md`) and register with `/skills`
-- Agents include `description` frontmatter and register with `/agents`
-- Run `worclaude doctor` to verify everything is wired up correctly
+### Hooks (8 lifecycle events)
 
-**Conditional Skills**
+Worclaude scaffolds hooks across the full Claude Code lifecycle:
 
-- 6 skills activate only when relevant files are touched (testing, security, frontend, backend, verification, project-patterns)
-- 8 skills stay always-loaded for cross-cutting guidance
-- Saves context window budget by keeping domain-specific guidance out of unrelated work
+- **SessionStart** — auto-loads CLAUDE.md, PROGRESS.md, last session summary, and recent learnings
+- **PostToolUse** — auto-formats code after every edit, using the right formatter for your stack
+- **PostCompact** — re-reads key files after context compaction so Claude stays oriented
+- **PreCompact** — emergency git snapshot before auto-compaction
+- **UserPromptSubmit** — detects correction signals and suggests skills based on prompt content
+- **Stop** — extracts `[LEARN]` blocks from the transcript and persists them to disk
+- **SessionEnd / Notification** — quiet-by-default session-end and desktop alerts
 
-**Agent Enhancements**
+Three profiles via `WORCLAUDE_HOOK_PROFILE`: `minimal` (context hooks only), `standard` (all hooks, default), `strict` (standard + TypeScript checking on every edit).
 
-- Read-only agents blocked from file modifications via `disallowedTools`
-- Background execution for long-running agents (verify-app, build-validator, e2e-runner)
-- Turn limits (`maxTurns`) prevent runaway token consumption
-- Persistent memory for agents that learn across sessions (test-writer, security-reviewer, doc-writer)
+### Learnings System
 
-**New Content**
+A personal, gitignored store at `.claude/learnings/` captures corrections and rules Claude picks up mid-session and replays them at the start of future sessions. The `correction-detect.cjs` and `learn-capture.cjs` hooks do this automatically; the `/learn` slash command is the explicit capture path. Unlike CLAUDE.md (shared rules, in git), learnings are yours — useful for personal conventions that should not leak into the repo. Promote a learning to CLAUDE.md when it matures into something every contributor should follow.
 
-- Coordinator-mode skill for multi-agent orchestration patterns
-- Agents with `memory: project` leverage Claude Code's native memory system
-- Enhanced verify-app agent with structured verdicts and adversarial probe requirements
-- Per-tech-stack permission presets (16 languages)
+### Cross-Tool Compatibility
 
-**Upgrade Migration**
+`AGENTS.md` is scaffolded alongside `CLAUDE.md` as a single source of truth for Cursor, Codex, GitHub Copilot, and other AI coding tools that expect `AGENTS.md`. Switching tools does not require maintaining parallel rule files.
 
-- `worclaude upgrade` auto-migrates v1.x projects: flat skills → directory format, agents get required frontmatter
-- `worclaude doctor` detects old formats and missing fields
+### Doctor
 
-**v2.2.0 — Leaner Defaults, Richer Skills**
+`worclaude doctor` runs a four-category health check: core files (workflow-meta, CLAUDE.md, settings.json), components (agents, commands, skills, agent-routing), documentation (PROGRESS.md, SPEC.md), and integrity (file hashes, hook-event validity, deprecated models, CLAUDE.md line budget, learnings index integrity, gitignore coverage). Every check reports PASS/WARN/FAIL with actionable diagnostics.
 
-- Removed project-root MEMORY.md scaffolding — Claude Code's native memory system handles this automatically
-- Expanded context-management, claude-md-maintenance, and coordinator-mode skills with deeper guidance
-- Enhanced verify-app agent with mobile, database migration, and data/ML pipeline verification patterns
+### Configuration
 
-See the [Claude Code Integration guide](https://sefaertunc.github.io/Worclaude/guide/claude-code-integration) for technical details.
+Pre-configured permissions per tech stack (Node.js, Python, Go, Rust, and 12 more), a CLAUDE.md template with progressive disclosure via skills, sandbox / effort / output defaults out of the box.
 
 ---
 
 ## Quick Start
 
+```bash
+npx worclaude init
+```
+
+Or install globally:
+
 ```bash
 npm install -g worclaude
 cd your-project
@@ -103,22 +109,26 @@ worclaude init
 
 Follow the interactive prompts to select your project type, tech stack, and agents. Then open Claude Code and run `/setup` to fill in your project-specific content.
 
-For parallel tasks, run Claude with worktrees: `claude --worktree --tmux`
+For parallel tasks, launch Claude with worktrees:
+
+```bash
+claude --worktree --tmux
+```
 
 ---
 
 ## Commands
 
-| Command             | Description                                    |
-| ------------------- | ---------------------------------------------- |
-| `worclaude init`    | Scaffold workflow into new or existing project |
-| `worclaude upgrade` | Update universal components to latest version  |
-| `worclaude status`  | Show current workflow state and version        |
-| `worclaude backup`  | Create timestamped backup of workflow files    |
-| `worclaude restore` | Restore from a previous backup                 |
-| `worclaude diff`    | Compare current setup vs latest version        |
-| `worclaude delete`  | Remove worclaude workflow from project         |
-| `worclaude doctor`  | Validate workflow installation health          |
+| Command             | Description                                                 |
+| ------------------- | ----------------------------------------------------------- |
+| `worclaude init`    | Scaffold workflow into new or existing project              |
+| `worclaude upgrade` | Update universal components to the latest version           |
+| `worclaude status`  | Show current workflow state, version, and npm update status |
+| `worclaude backup`  | Create a timestamped backup of workflow files               |
+| `worclaude restore` | Restore from a previous backup                              |
+| `worclaude diff`    | Compare current setup vs latest template                    |
+| `worclaude delete`  | Remove worclaude workflow from project                      |
+| `worclaude doctor`  | Validate workflow installation health                       |
 
 The `init` command detects existing setups and merges intelligently — no data is overwritten without your confirmation. Use `upgrade` to pull in new features while preserving your customizations.
 
@@ -126,9 +136,27 @@ See the [full command reference](https://sefaertunc.github.io/Worclaude/referenc
 
 ---
 
+## Why Worclaude
+
+- **Split architecture.** CLAUDE.md stays under 200 lines for speed; detail lives in skills loaded on demand. Personal rules live in `.claude/learnings/` (gitignored); shared rules live in CLAUDE.md.
+- **Learning loop.** Correct Claude once, it captures the rule, the next session picks it up at start — no re-stating.
+- **Cross-tool ready.** `AGENTS.md` generated from the same source as CLAUDE.md, so your rules work in Cursor / Codex / Copilot too.
+- **Hook profiles.** Dial strictness up or down via one environment variable. `minimal` for CI, `standard` for daily work, `strict` for type-heavy projects.
+- **Smart merge.** Detects existing Claude Code setups and merges additively — existing files never overwritten without confirmation. Three-tier strategy: additive for missing content, safe-alongside for conflicts, interactive for CLAUDE.md.
+- **Self-healing doctor.** Catches drift, stale hashes, deprecated models, broken learnings — before they bite.
+
+---
+
 ## Links
 
-- [Full Documentation](https://sefaertunc.github.io/Worclaude/)
-- [Interactive Demo](https://sefaertunc.github.io/Worclaude/demo/)
+- [Full Documentation](https://sefaertunc.github.io/Worclaude/) — VitePress site with guides and reference
+- [npm Package](https://www.npmjs.com/package/worclaude)
+- [GitHub Issues](https://github.com/sefaertunc/Worclaude/issues)
 - [Contributing](CONTRIBUTING.md)
+- [Code of Conduct](CODE_OF_CONDUCT.md)
+- [Security Policy](SECURITY.md)
 - [License: MIT](LICENSE)
+
+---
+
+Built on [Boris Cherny's Claude Code tips](https://www.howborisusesclaudecode.com/). MIT licensed.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "worclaude",
-  "version": "2.2.5",
-  "description": "CLI tool that scaffolds a comprehensive Claude Code workflow into any project",
+  "version": "2.3.0",
+  "description": "The Workflow Layer for Claude Code — scaffold agents, commands, skills, hooks, and memory into any project",
   "type": "module",
   "bin": {
     "worclaude": "./src/index.js"
@@ -11,6 +11,7 @@
     "src/",
     "templates/",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "repository": {
@@ -39,8 +40,12 @@
   "keywords": [
     "claude",
     "claude-code",
+    "claude-code-workflow",
+    "claude-code-scaffolding",
     "workflow",
     "scaffolding",
+    "hooks",
+    "memory",
     "cli",
     "developer-tools",
     "productivity",