v2.21.0 — Orchestrate Pipeline & Insights Lifecycle

Highlights

• /craft:orchestrate:plan Command — New pipeline from spec → ORCHESTRATE → worktree. Discovers specs, parses phases, generates session-ready ORCHESTRATE files with friction prevention, and creates worktrees for isolated development.
• /craft:insights Command — Generates usage pattern reports from session facets data. Aggregates friction patterns, goal categories, and CLAUDE.md suggestions. Supports --format html|terminal|json and --since <days> filtering.
• Brainstorm → Orchestrate Pipeline — New Step 6 offers ORCHESTRATE + worktree creation after spec capture, connecting the full workflow: brainstorm → spec → ORCHESTRATE → worktree → implement → PR.
• Brainstorm Insights Integration — New Step 1.8 checks session insights for relevant past friction patterns before brainstorming.
• AskUserQuestion Enforcement — Brainstorm command now uses exact JSON tool call syntax instead of prose references.

New Features

• Worktree Types Taxonomy: 4-type system (Manual, Pipeline, Swarm, Cross-Repo) documented across REFCARD, orchestrate command, worktree reference, and tutorials
• Swarm Clarity: Enhanced --swarm documentation with practical dry-run examples and decision guidance
• Cross-Command Integration: Insights wired into /craft:do routing, /craft:hub discovery, and /craft:check --context mode
• Insights Lifecycle: Full documented flow from sessions → facets → insights → CLAUDE.md rules

New Files

File	Purpose
commands/orchestrate/plan.md	Spec → ORCHESTRATE → worktree pipeline
commands/workflow/insights.md	Session insights report command
docs/guide/pipeline-orchestrate-guide.md	Pipeline guide (237 lines)

Stats

• 111 commands | 25 skills | 8 agents | ~1575 tests passing
• 42 files changed

Full Changelog: v2.20.0...v2.21.0

v2.20.0 — Homebrew Refactor: Security, Subcommands & Release Hardening

Highlights

• Workflow Security Hardening — env indirection prevents script injection, sha256sum + --retry 3 + 64-char SHA guard in homebrew-release.yml
• Subcommand Consolidation — 8 → 6 subcommands: validate → audit (with --build), token folded into setup, release-batch dropped, deps expanded with inter-formula graph
• Formula Name Mapping — .craft/homebrew.json config with 3-priority lookup chain (config → git remote → basename)
• Release Skill Hardening — Step 8.5 uses shasum -a 256 (macOS-portable), ruby -c syntax validation, SHA guard
• New Documentation — Homebrew Automation Guide (310 lines), Setup Tutorial, Quick Reference Card

Changes

Security

• homebrew-release.yml: env indirection for github.event_name and github.event.inputs.version
• SHA256 calculation: sha256sum on CI (Ubuntu), shasum -a 256 in release skill (macOS)
• curl --retry 3 --retry-delay 2 for resilient downloads
• 64-char hex guard catches empty/corrupt SHA before workflow proceeds
• ruby -c validates formula syntax after sed updates

Commands

• dist:homebrew: 8 → 6 subcommands (formula, workflow, audit, setup, update-resources, deps)
• audit: replaces validate, adds --build flag for brew install --build-from-source
• deps: inter-formula dependency graph + system deps matrix + --dot Graphviz output
• token: folded into setup wizard Step 4

Configuration

• .craft/homebrew.json: formula name + tap + source type config
• Release skill Step 8.5: 3-priority lookup (config → git remote → basename)

Documentation

• New: docs/guide/homebrew-automation.md (310 lines)
• New: docs/tutorials/TUTORIAL-homebrew-setup.md
• New: docs/reference/REFCARD-HOMEBREW.md
• Updated: dist commands, REFCARD, homebrew installation guide

Tests

• 50 new dogfood tests (test_homebrew_refactor_dogfood.py)
• 47 new e2e tests (test_homebrew_refactor_e2e.sh)

Stats

109 commands | 25 skills | 8 agents | ~1575 tests passing

Full Changelog: v2.19.0...v2.20.0

v2.19.0 — Marketplace & Insights-Driven Improvements

Highlights

• Marketplace Distribution — First-class dist:marketplace command for publishing to the Claude Code marketplace, with marketplace.json schema and GitHub source integration
• Insights-Driven Improvements — Guard audit skill (5-step pipeline), insights apply skill, autonomous releases, context-only checks, worktree validation, swarm orchestration
• Guard Audit Skill — Analyzes branch-guard.sh rules for false positives and proposes JSON config changes (read-only, never modifies guard script)
• Autonomous Releases — --autonomous flag for unattended release pipeline with --admin safety warnings and audit trail
• PreToolUse Hook — Python hook that warns when file operations target paths outside the current worktree

Changes

Features

• Add dist:marketplace command for marketplace distribution channel
• Add guard-audit skill — 5-step branch guard audit pipeline
• Add insights-apply skill — extracts and applies CLAUDE.md suggestions from insights reports
• Add --autonomous flag to release skill for unattended pipelines
• Add --context flag to check command for context-only phase detection
• Add validate action to worktree command for health checks
• Add --swarm flag to orchestrate command for unlimited parallel agents
• Add PreToolUse Python hook for worktree path validation

Fixes

• Fix VERSION-HISTORY v2.17.0 status (was "In Development", now "Released")
• Fix phase detection gap in check command (pr-prep now checks both PR exists AND clean tree)
• Add safety warning for --autonomous --admin override in release skill, tutorial, and guide
• Reconcile marketplace schema with spec, fix stale counts
• Use GitHub source object in marketplace.json

Documentation

• Marketplace distribution guide, tutorial, and getting-started integration
• Insights-driven improvements guide (7 Mermaid diagrams) and tutorial (9 steps)
• Hub, REFCARD, and QUICK-START updated with new features

Tests

• 57 marketplace distribution tests (dogfood + e2e)
• 89 insights improvements tests (59 dogfood + 30 e2e)

Stats

• 109 commands | 25 skills | 8 agents | ~1575 tests passing
• 33 commits since v2.18.0

Full Changelog: v2.18.0...v2.19.0

v2.18.0 — Release Pipeline Enhancements

Highlights

• CI mirror pre-flight — /craft:check --for release now runs full test suite, lint, and security as Step 2a in the release pipeline, catching failures before push
• README/index version checks — pre-release-check.sh now validates version badges in README.md and docs/index.md (check 4/5), preventing stale versions in releases
• Release command delegation — /craft:code:release detects Craft plugins and delegates to the skill's 10-step pipeline automatically
• CLAUDE.md trimmed 74% — 587 → 155 lines via lean pointer architecture

Changes

Features

• Add /release skill for end-to-end release pipeline automation (10-step pipeline with dry-run)
• Add release skill tests (e2e + dogfooding), dry-run mode, refcard, and tutorial
• Add /craft:check --for release as CI mirror pre-flight (Step 2a)
• Add README.md and docs/index.md version checks to pre-release-check.sh (check 4/5)

Documentation

• Trim CLAUDE.md from 587 to 155 lines (74% reduction)
• Sync release pipeline docs across all tutorials, refcards, guides, and workflows
• Update /craft:code:release to delegate to release skill for Craft projects
• Correct skill count: 21 → 23 across all docs

Fixes

• Update orch-flag test to check VERSION-HISTORY.md instead of CLAUDE.md (avoids content-coupling anti-pattern)

Stats

• 108 commands | 23 skills | 8 agents | ~1504 tests passing
• 9 commits since v2.17.0

Full Changelog: v2.17.0...v2.18.0

v2.17.0 — Branch Guard v2: Smart Protection Mode

Branch Guard v2: Smart Protection Mode

Highlights

• 3-tier risk classification (LOW/MEDIUM/HIGH) replaces binary block/allow
• Fade-to-brief learning — verbosity decreases over your session
• One-shot approvals with 5-min TTL — stale markers auto-expire
• Destructive command detection — blocks dangerous git operations and rm variants targeting .git
• Critical file protection — blocks writes to .env, .pem, .key, branch-guard.json on dev
• Bash write-through detection — catches redirect/tee/cp creating new code files on dev

Code Review Fixes

• Race condition: flock-based atomic append to session counter
• TOCTOU: file existence re-check after age-out
• Broadened rm .git regex to catch all flag ordering variants

Documentation

• Smart mode guide (docs/guide/branch-guard-smart-mode.md)
• Setup tutorial (docs/tutorials/TUTORIAL-branch-guard-setup.md)
• Quick reference card (docs/reference/REFCARD-BRANCH-GUARD.md)
• Updated mkdocs.yml navigation and index page

Tests

• 1449 total tests (up from 1432)
• 155 branch guard tests: 94 unit + 31 e2e + 17 review fixes + 6 integration + 7 dogfood

Full Changelog: v2.16.0...v2.17.0

v2.16.0 — Teaching Ecosystem + Branch Protection

What's New

Branch Protection Hooks

• scripts/branch-guard.sh — PreToolUse hook that prevents edits on protected branches
• Protection levels: block-all (main) blocks all writes; block-new-code (dev) blocks new code files but allows docs/specs/existing edits
• Bypass: /craft:git:unprotect creates a marker file; /craft:git:protect removes it
• Dry-run mode: .claude/branch-guard-dryrun marker logs blocks but allows through
• New commands: /craft:git:protect and /craft:git:unprotect
• 138 tests: 49 unit + 31 e2e + 6 integration + 52 dogfooding

Teaching Ecosystem Coordination

• Config normalizer: _normalize_config() maps flow-cli schema to Craft-native format
• Single-day break support: Break validation now accepts start == end for holidays
• 8 normalization tests in teaching workflow integration suite
• Dedicated Teaching tab in docs site navigation

Housekeeping

• Archived 23 completed specs to docs/specs/_archive/
• Fixed 12+ broken links from spec archival
• Test count: 1294 → 1432 (+138)
• Command count: 106 → 108 (+protect, +unprotect)

Full Changelog: v2.15.0...v2.16.0

v2.15.0 — Brainstorm v2.5.0: Spec Simplification + Smart Questions

Brainstorm v2.5.0: Spec Simplification + Smart Questions

Spec Simplification (84% reduction)

• Brainstorm command spec: 1,919 → 312 lines (84% reduction)
• Extracted to 4 reference documents:
  • docs/specs/SPEC-brainstorm-question-bank.md — Full question bank with all Q&A text
  • docs/tutorials/TUTORIAL-brainstorm-power-user.md — Power user guide with advanced patterns
  • docs/reference/REFCARD-BRAINSTORM.md — Quick reference card with flowchart
  • docs/VERSION-HISTORY.md — Brainstorm evolution table (v2.1→v2.5)

Context-Aware Smart Questions

• New utility: utils/brainstorm_context.py (~280 lines)
  • Scans .STATUS, docs/specs/, git log, CLAUDE.md for project context
  • Pre-fills answers from existing project state
  • Detects prior brainstorms, matching specs, failing tests
• Project-type question extensions: 6 types (R, Python, Node.js, Quarto, Claude Plugin, Teaching) with 12 new questions
• Dynamic questions: Matching spec detection, prior brainstorm resume, failing test alerts

Tests

• 38 new tests in tests/test_brainstorm_context.py (all passing)
• 53 + 24 existing brainstorm tests verified
• 1286 total tests across the project

Documentation

• 3 new nav entries in mkdocs.yml
• Version refs synced across README, docs/index.md, CLAUDE.md, mkdocs.yml
• All CI checks passing

Full Changelog: v2.14.0...v2.15.0

v2.14.0 — Unified Formatting Library

What's New

Unified Formatting Library (scripts/formatting.sh)

Shared bash library (~180 lines) providing box-drawing (double/single line), FMT_ prefixed color constants, ANSI-aware padding, table formatting, and source guard. All boxes standardized to 63 visible characters.

API: box_header, box_single, box_row, box_separator, box_footer, box_empty_row, box_table, fmt_set_width, fmt_divider, _fmt_strip_ansi

Migrations

• 8 box-drawing scripts migrated (install.sh, migrate-from-workflow.sh, convert-cast.sh, health-check.sh, consent-prompt.sh, dependency-installer.sh, dependency-manager.sh)
• 15 color-only scripts migrated (validate-counts, pre-release-check, batch-convert, repair-tools, 3 installers, tool-detector, version-check, sync-version, verify-phase1/2, install-hooks, test-fix-flag, pre-commit-markdownlint)

Tests

• 74 new tests (28 unit + 30 integration + 16 edge cases)
• 1248 total tests passing

Documentation

• Formatting library guide, migration tutorial, reference card

Full Changelog: v2.13.1...v2.14.0

v2.13.1 — Fix plugin.json strict schema compatibility

What's Changed

Fixed

• Plugin loading: Moved claude_md_budget from plugin.json to .claude-plugin/config.json — Claude Code's strict schema rejects unrecognized keys, silently breaking plugin loading (anthropics/claude-code#20415)
• Budget utilities: Updated claude_md_optimizer.py, claude_md_sync.py, and claude-md-budget-check.sh to read budget from config.json
• Homebrew formula: Dual-protection JSON cleanup in post_install — Ruby allowlist strips unrecognized keys + Python fallback in craft-install script

Changed

• Budget config fallback chain: .claude-plugin/config.json → package.json (claudeMd.budget) → default 150
• Updated sync command docs, conventions, spec, changelog, and CLAUDE.md troubleshooting

Files Changed

10 files changed (+111/-59)

Full Changelog: v2.13.0...v2.13.1

v2.13.0 — Documentation Gap-Fill

What's New

30 new documentation pages filling gaps across the entire docs site, plus CLAUDE.md v3 command refactoring.

Documentation Gap-Fill

• 5 beginner cookbook recipes (find-command, update-doc, code-checks, git-branch, view-architecture)
• 8 troubleshooting guides (timeouts, wrong output, CI fails, pre-commit, worktree, broken links, CLAUDE.md sync, mkdocs)
• 1 beginner tutorial — "Your First 10 Minutes with Craft"
• 13 individual command pages (arch, code, test, git, docs)
• 4 category decision guides with "When to Use What" tables
• 7 broken links fixed, documentation status 98% → 99%

CLAUDE.md v3 Command Refactoring

• Command consolidation: scaffold→init, update/audit/fix→sync, edit with --global flag
• New utilities: claude_md_optimizer.py (1,030 lines), claude_md_sync.py (1,465 lines)
• Pointer templates with -> syntax for lean CLAUDE.md files
• Budget enforcement via scripts/claude-md-budget-check.sh
• 71 new tests (51 unit + 9 integration + 11 audit)

Stats

• 106 commands · 21 skills · 8 agents
• 1,174 tests passing · 99% documentation coverage
• Site: https://data-wise.github.io/craft/

Full Changelog: v2.12.0...v2.13.0