Skip to content

v3.1.0 — new commands + /merge dual-mode + maintenance-engine README

Latest

Choose a tag to compare

@peterkrueck peterkrueck released this 18 May 15:20
· 1 commit to main since this release

A polish-and-fix release: new commands, safer /merge, and the README rewritten around what the kit actually does (maintain Claude's context layer across sessions, not just ship templates).

Added

  • /plan-feature command — Designed for use inside Plan Mode (Shift+Tab). Encodes the pattern: parallel research sub-agents → state tradeoffs (not just choices) → Context7 first for libraries → /review-work before final verification → /second-opinion before exiting plan mode.
  • /prime --deploy flag — Optional flag that loads docs/ai-context/deployment-infrastructure.md in addition to the three core docs. Deployment infra is stable and often large; loading it on every routine /prime wastes context. Read it only when you're actually touching deploy/infra/CI work.
  • /second-opinion model override — New CLAUDE_SECOND_OPINION_MODEL env var lets users self-rescue when Google deprecates the pinned gemini-3.1-pro-preview (preview models rotate fast). Every bash invocation uses the ${CLAUDE_SECOND_OPINION_MODEL:-gemini-3.1-pro-preview} pattern. Expanded error detection distinguishes capacity-exhausted (transient) from model-deprecated (permanent) failures and tells the user exactly how to recover.
  • Operator Model template sections — New commented sections in templates/CLAUDE.md (§2) and templates/GEMINI.md describing the solo-founder / AI-agent collaboration model. Especially valuable for AI-agent-driven workflows where "over-engineered for a solo dev" is rarely valid critique.
  • Worked deploy example — The /deploy template skill now includes a filled-in worked example (Node.js + Fly.io stack) so users see what the placeholders look like once customized. Stays a template — the example is reference, not the actual skill.

Changed

  • /merge command — full rewrite for safety, then dual-mode for reach. Previously auto-invoked /update-docs, auto-staged with implicit commit logic, had no clean-tree check, AND required a git worktree (regular-branch users couldn't use it at all). New version is verify + ship, supports both flows:
    • Pre-flight auto-detects mode by comparing git rev-parse --git-dir to --git-common-dir. Equal → standard mode (git checkout main && git merge ...). Different → worktree mode (git -C <main-repo-path> merge ... + ExitWorktree).
    • \$ARGUMENTS conventions: Verified: <context> (opt-in commit annotation) and summary: <override> (skip auto-synthesis of merge message).
    • Docs-currency guardrail: if substantive diff lacks doc touches → STOPS and asks user (abort / proceed-with-drift / cancel). Never auto-invokes `/update-docs`.
    • Clean-tree guardrail: dirty tree → STOPS and asks user to name files explicitly. Never `git add -A` or `.`.
    • Adds `git branch -d ` cleanup so a future branch (or worktree) with the same name doesn't reuse a stale ref.
  • README restructured around the "maintenance engine" framing. Leads with the problem (static `CLAUDE.md` decay, session continuity loss) then the loop (`/prime` → work → `/review-work` → `/update-docs` → `/merge`) instead of a parts list. Adds `/merge` and `/plan-feature` to the installed-commands list and file tree (both previously missing).
  • setup.sh in-installer tutorial extended to 8 steps including `/merge`. Footer mentions `/plan-feature` for Plan Mode users. Post-install "test your setup" line shows the `/prime → /merge` workflow pair. Version banner bumped from v3.0.0 to v3.1.0.

Template renumbering

  • `templates/CLAUDE.md` sections renumbered to accommodate new §2 Operator Model: previous 2→3 (Architecture Decisions), 3→4 (Tool Usage), 4→5 (Coding Standards), 5→6 (Testing), 6→7 (Privacy & Security). Existing users with customized `CLAUDE.md` files are unaffected (the installer preserves existing files).

Full details: see CHANGELOG.md.

Install or upgrade:
```bash
curl -fsSL https://raw.githubusercontent.com/peterkrueck/Claude-Code-Development-Kit/main/install.sh | bash
```