Release v11.9.1

[11.9.1] - 2026-04-23

✨ Added

Source-of-Truth Contract for the Spec-Flow Source Repo

• Added CONTEXT.md to lock the repo boundary between source/distribution assets and downstream consumer-project state
• Declared .spec-flow/ as the shared canon and .claude/ / .codex/ as adapter surfaces over that canon
• Reclassified checked-in examples and maintainer docs so public docs only describe shipped, user-facing surfaces

🔧 Improved

Workflow Surface Truthfulness

• Public docs now distinguish installer CLI commands (npx spec-flow ...) from installed workflow commands
• spec-cli.py now documents planned and compatibility-only surfaces honestly instead of implying full shared runtimes where none are shipped
• Shared epic and scheduler support now route the shipped subset through shared scripts while clearly labeling the remaining planned runtime

🐛 Fixed

Shared Engine Compatibility and CI

• Replaced broken phase shell payloads with executable compatibility shims for tasks, validate, implement, and preview
• Added missing PowerShell wrapper coverage for shipped shared-script entrypoints
• Fixed check-prerequisites.sh ShellCheck compliance so main CI is green again before release

v11.9.0

✨ Added

shadcn/ui Integration with 8 Customization Options

The /init --tokens command now generates both OKLCH design tokens (source of truth) AND shadcn/ui-compatible CSS variables through the Token Bridge Pattern:

• 8 customization options: Style Preset, Base Color, Theme Mode, Icon Library, Font Family, Border Radius, Menu Color, Menu Accent
• Token Bridge Pattern: OKLCH tokens remain the accessible source of truth, with shadcn CSS variable aliases generated automatically
• Brownfield scanning: Automatically detects and consolidates existing color tokens
• Component integration: Generated components.json works directly with shadcn CLI
• Menu theming: New menu-specific tokens for background, hover, active, and accent styles

New files:

• .spec-flow/scripts/node/generate-shadcn-tokens.js - Token generation engine
• .claude/skills/shadcn-integration/SKILL.md - Integration skill documentation
• .spec-flow/templates/design/shadcn-variables.css - shadcn variable template
• .spec-flow/templates/design/menu-variants.ts - Menu component variants

Ultrathink Philosophy Checkpoints Across Workflow Phases

Ultrathink principles are now embedded as lightweight checkpoints throughout the workflow, not just during explicit /ultrathink invocations:

Phase	Principle	Checkpoint
/spec	Think Different	Assumption inventory before requirements
/plan	Obsess + Simplify	Codebase soul analysis, 3 alternatives, complexity budget
/tasks	Simplify Ruthlessly	Task count validation, simplification review
/implement	Craft, Don't Code	Anti-duplication ritual, abstraction justification

Progressive depth based on complexity:

• Trivial (<5 tasks): Skip checkpoints, fast path
• Standard (5-30 tasks): Lightweight inline checkpoints
• Complex (30+ tasks): Full checkpoints + separate artifacts
• Epic (multi-sprint): Mandatory deep planning + craftsman-decision.md

New files:

• .spec-flow/config/ultrathink-integration.yaml - Checkpoint configuration

🔧 Improved

Ultrathink Command Enhancements

• Added skill reference for context
• Added proper AskUserQuestion JSON format for roadmap materialization
• Added pre-flight checks for gh CLI authentication
• Added error handling for GitHub issue creation
• Fixed inconsistent terminology

---

Full Changelog: v11.8.4...v11.9.0

v11.8.4

✨ Added

Worktree Branch Sync

• Worktrees now fetch origin/main before creating branches, ensuring they start up-to-date
• New worktree-manager.sh sync <slug> command to rebase existing worktrees onto latest main
• Prevents "This branch is out of date from base branch" warnings in GitHub PRs

🐛 Fixed

• Branches are now created from origin/main instead of local main which may be stale

---

Full Changelog: v11.8.3...v11.8.4

v11.8.3

🐛 Fixed

Script Path References in feature-workflow.sh

• Fixed undefined $SCRIPT_DIR variable causing worktree creation to fail
• Corrected paths to use relative paths from repo root (.spec-flow/scripts/bash/...)

---

Full Changelog: v11.8.2...v11.8.3

v11.8.2 - Worktree creation in /feature command

✨ Added

Worktree Creation in /feature Command

The /feature command now creates isolated git worktrees by default:

• Automatic worktree creation: Running /feature "description" creates worktrees/feature/XXX-slug/ instead of just a branch
• State tracking: Stores git.worktree_enabled and git.worktree_path in state.yaml
• Clear output: Shows worktree path and cd command for easy navigation
• Graceful fallback: Falls back to regular branch if worktree creation fails
• Configurable: Set worktrees.auto_create: false in preferences to disable

This completes the v11.8.0 worktree-first safety model - now features actually create worktrees.

---

Full Changelog: v11.8.1...v11.8.2

v11.8.1 - Fix package distribution

🐛 Fixed

Package Distribution Missing Essential Files

• Fixed .npmignore excluding dist/ folder which prevented CLAUDE.md and QUICKSTART.md from being included in the npm package
• Users running npx spec-flow init or npx spec-flow update no longer see "Package is corrupted" errors

---

Full Changelog: v11.8.0...v11.8.1

v11.8.0 - Worktree-First Safety Model

✨ Added

Worktree-First Safety Model for Multi-Agent Isolation

Run multiple Claude Code instances from root folder with automatic git isolation - each agent works in its own worktree with namespaced branches.

• Studio context detection: Auto-detect when running in worktrees/studio/agent-N/ directories
  • detect_studio_context(): Returns agent ID (e.g., agent-1) if in studio worktree
  • is_studio_mode(): Boolean check for studio context
• Branch namespacing: Studio agents get isolated branch names
  • Studio mode: studio/agent-N/feature/XXX-slug
  • Normal mode: feature/XXX-slug
  • Prevents git conflicts during parallel development
• Root safety checks: Block changes from root when active worktrees exist
  • find_active_worktrees(): List all in-progress features/epics in worktrees
  • check_root_safety(): Returns safe/blocked status with recommended action
• PHASE 0.5 safety check: Added to /feature, /epic, /quick commands
  • Runs before any work begins
  • Blocks or prompts based on protection level

New Worktree Preferences

• worktrees.enforce_isolation: Require worktree isolation for all implementation (default: true)
• worktrees.root_protection: Protection level when in root with active worktrees
  • strict: Block changes, require switch to worktree (default)
  • prompt: Ask user to confirm root changes
  • none: Allow changes without protection
• worktrees.auto_switch_on_continue: Auto-prompt to switch when resuming from root (default: true)
• worktrees.cleanup_on_finalize: Remove worktree after deployment (default: true)

Worktree Cleanup at Finalize

• /finalize now cleans up worktree when cleanup_on_finalize is enabled
• Agent returns to root repository for next work
• Safe deletion only (preserves unmerged changes)

Studio Mode Integration

• /feature, /epic, /quick automatically detect studio context
• Branch names auto-namespaced for studio agents
• PR-based shipping for studio agents (like real dev teams)
• No code changes needed in existing workflows

🔧 Changed

• User preferences schema: Added worktrees section (v1.6)
• worktree-context.sh: Central script for all worktree management
• CLAUDE.md: Added Studio Mode and Worktree-First Safety documentation

---

Full Changelog: v11.7.0...v11.8.0

Release v11.7.0

Auto-Mode for End-to-End Workflow Execution

Run entire workflows without stopping - from specification through deployment with a single flag.

✨ Added

• --auto flag: Added to /feature and /epic commands
  • Continue automatically through optimize → ship → finalize without stopping
  • Skip manual approval prompts (proceed automatically)
  • Auto-merge PR when CI passes (controlled by preference)
• /ship --auto: Full autopilot for deployment phase
  • Skip production approval prompt
  • Auto-merge when CI passes
  • Continue to /finalize automatically

New Deployment Preferences

• deployment.auto_ship: Continue from optimize → ship → finalize without pausing (default: false)
• deployment.auto_merge: Auto-merge PR when CI passes, no approval prompt (default: false)
• deployment.auto_finalize: Run /finalize automatically after deployment (default: true)

Full Autopilot Example

# .spec-flow/config/user-preferences.yaml
deployment:
  auto_ship: true
  auto_merge: true
  auto_finalize: true

Then run: /feature "add auth" --auto → Runs spec → plan → tasks → implement → optimize → ship → finalize automatically.

🔧 Changed

• User preferences schema: Added deployment section (v1.5)
• Phase configuration: Updated to pass --auto flag through workflow phases

v11.6.1: Fix Initializer Agent Tool Execution

🐛 Fixed

Initializer Agent Tool Execution

The initializer agent was planning but not executing tools (0 tool uses despite 10k tokens of output).

• Root cause: Agent instructions used code blocks as documentation examples, agent treated them as text to output rather than commands to execute
• Fix: Added explicit "MUST use tools" constraints, anti-pattern warnings, verification steps, and fallback direct-write mechanism
• Affected file: .claude/agents/domain/initializer.md

---

Full Changelog: v11.6.0...v11.6.1

v11.6.0: Dry-Run Mode & Ultrathink-Roadmap Integration

✨ Added

Dry-Run Mode for Commands

Preview command effects without making changes - perfect for learning, testing, and CI validation.

• --dry-run flag: Added to /feature, /implement, /ship, /debug
  • Simulates file writes, git operations, agent spawns, state changes
  • Safe operations (reads) execute normally for accurate context
  • Standardized output format with emoji prefixes (📋, 📁, 📝, 🔀, 🤖)
• Dry-run skill: New .claude/skills/dry-run/SKILL.md with integration patterns

Ultrathink → Roadmap Integration (v2.0)

Transform deep thinking sessions into actionable GitHub Issues with full traceability.

• Phase 5: Materialize the Thinking: Extract features during analysis
• Structured YAML output: specs/ultrathink/[slug].yaml
• New flags: --roadmap (save + create issues), --save (save only), --no-save (ephemeral)

Roadmap from-ultrathink Action

• /roadmap from-ultrathink [path]: Materialize features from saved ultrathink sessions
• /roadmap from-ultrathink --list: List available sessions

🔧 Changed

• Ultrathink location: Moved from /internal:ultrathink to /core:ultrathink

🐛 Fixed

• Debug command: Fixed bash syntax error with $(pwd) in context section

---

Full Changelog: v11.5.0...v11.6.0