feat: add writing-plans skill and execution workflow improvements

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "superpowers",
-  "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
+  "description": "Core skills library with writing-plans skill and automation-over-documentation guidance",
   "version": "3.6.2",
   "author": {
     "name": "Jesse Vincent",
@@ -9,5 +9,5 @@
   "homepage": "https://github.com/obra/superpowers",
   "repository": "https://github.com/obra/superpowers",
   "license": "MIT",
-  "keywords": ["skills", "tdd", "debugging", "collaboration", "best-practices", "workflows"]
+  "keywords": ["skills", "tdd", "debugging", "collaboration", "best-practices", "workflows", "writing-plans"]
 }

.codex/superpowers-codex

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const skillsCore = require('../lib/skills-core');
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import * as skillsCore from '../lib/skills-core.js';
 
 // Paths
 const homeDir = os.homedir();

CLAUDE.md

@@ -0,0 +1,248 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a **Claude Code plugin** that provides a core skills library. Unlike traditional Node.js projects, this repository contains **no build system, no package.json, and no traditional test suite**. Skills are markdown documentation files that are loaded directly by Claude Code.
+
+**Key Architecture:**
+
+- `skills/` - 21 skills organized by category (testing, debugging, collaboration, meta)
+- `commands/` - Slash commands that activate corresponding skills
+- `agents/` - Agent definitions (e.g., code-reviewer)
+- `hooks/` - Session lifecycle hooks (auto-loads skills system)
+- `.claude-plugin/` - Plugin manifest and marketplace configuration
+- `llm/` - Local-only planning documents (NOT tracked by git)
+
+## Development Workflow
+
+### Creating New Skills
+
+**Don't improvise.** Use the meta-skills that define the process:
+
+1. **Read `skills/writing-skills/SKILL.md` first** - Complete TDD methodology for documentation
+2. **Test with `skills/testing-skills-with-subagents/SKILL.md`** - Run baseline tests, verify skill fixes violations
+3. **Contribute with `skills/sharing-skills/SKILL.md`** - Fork, branch, test, PR workflow
+
+**TDD for Documentation Approach:**
+
+- RED: Run baseline with subagent (without skill) - observe failures
+- GREEN: Write skill that addresses violations - verify compliance
+- REFACTOR: Close loopholes, tighten language against rationalization
+
+### Local Plugin Development
+
+When developing superpowers locally and testing changes in Claude Code:
+
+1. **Edit skills** in the repository's `skills/` directory
+2. **Commit changes** to your branch
+3. **Reload plugin** to reflect changes in Claude Code (paste both lines):
+   ```bash
+   /plugin uninstall superpowers
+   /plugin install superpowers
+   ```
+4. **Test changes** in a new Claude Code session
+
+**Important:** Plugin changes only take effect after reload. Skills are loaded at session start, so existing sessions won't see updates.
+
+### PR Creation Safety
+
+**Approval pattern:** finishing-a-development-branch skill enforces preview-then-confirm for PR creation.
+
+**Expected flow:**
+1. User selects option 2 (Push and create PR)
+2. Claude pushes branch
+3. Claude shows PR title/body preview
+4. Claude asks: "Create this PR? (yes/no)"
+5. User must type "yes" to proceed
+
+**Defense-in-depth:**
+- Skill-level approval gate (primary)
+- Permission rules in ~/.claude/settings.json (secondary)
+- Permission system prompts on first use (tertiary)
+
+**Similar patterns:**
+- jira-publisher skill (safety-critical approval gates)
+- Option 4 discard confirmation (typed "discard" required)
+
+### Local Development with Worktrees
+
+**Use git worktrees to test changes in isolation while keeping main stable.**
+
+**Creating a worktree for experiments:**
+
+```bash
+# From main repository
+cd /path/to/superpowers
+
+# Create worktree with new branch
+git worktree add .worktrees/feature-name -b feature/my-experiment
+
+# Work in worktree
+cd .worktrees/feature-name
+# Edit skills, commit changes, then reload plugin:
+/plugin uninstall superpowers
+/plugin install superpowers
+# (Paste both lines together)
+```
+
+**When satisfied with changes:**
+
+```bash
+# Return to main
+cd /path/to/superpowers
+
+# Merge feature branch
+git merge feature/my-experiment
+
+# Remove worktree
+git worktree remove .worktrees/feature-name
+
+# Delete feature branch (optional)
+git branch -d feature/my-experiment
+```
+
+**Benefits:**
+- Main directory always stable
+- Test changes in isolation without affecting running Claude sessions
+- Run multiple worktrees for parallel experiments
+- Easy cleanup when done
+
+### Skill Structure Requirements
+
+**Directory and Naming:**
+
+```plaintext
+skills/
+  skill-name/           # lowercase-with-hyphens only (no special chars)
+    SKILL.md            # Required: main skill content
+    example.ts          # Optional: reusable tool/example code
+    scripts/            # Optional: supporting utilities
+    reference-docs.md   # Optional: heavy reference material
+```
+
+**Frontmatter (required in SKILL.md):**
+
+```yaml
+---
+name: skill-name # Must match directory name exactly
+description: Use when [trigger] - [what it does] # Appears in skill list
+---
+```
+
+**Supporting Files Patterns:**
+
+- Self-contained skill → Only `SKILL.md`
+- Skill with reusable tool → `SKILL.md` + `example.ts` (see `condition-based-waiting`)
+- Skill with heavy reference → `SKILL.md` + reference docs + `scripts/` (see `root-cause-tracing`)
+
+### Skill Types and Treatment
+
+1. **Discipline-Enforcing Skills** (e.g., `test-driven-development`, `verification-before-completion`)
+
+   - Contain rigid rules tested against pressure scenarios
+   - Follow exactly - don't adapt away the discipline
+
+2. **Technique Skills** (e.g., `condition-based-waiting`, `root-cause-tracing`)
+
+   - How-to guides with concrete steps
+
+3. **Pattern Skills** (e.g., `brainstorming`, `systematic-debugging`)
+
+   - Mental models and flexible patterns - adapt to context
+
+4. **Reference Skills**
+   - Heavy documentation, APIs, guides
+
+The skill itself indicates which type it is.
+
+## Testing Skills
+
+**No traditional test suite exists.** Skills are tested using:
+
+1. **Subagent Testing** - Spawn subagents with/without skill, compare behavior
+2. **Pressure Scenarios** - Test if agents comply when tempted to skip steps
+3. **Baseline Testing** - Run without skill to demonstrate violations
+4. **TDD Cycle** - Iteratively tighten language to close loopholes
+
+See `skills/testing-skills-with-subagents/SKILL.md` for complete methodology.
+
+## Contributing Workflow
+
+**Standard fork-based workflow:**
+
+1. Fork repository (if you have `gh` CLI configured)
+2. Create feature branch: `add-skillname-skill` or `improve-skillname-skill`
+3. Create/edit skill following `writing-skills` guidelines
+4. Test with subagents to verify behavior changes
+5. Commit with clear message (avoid mentioning "Claude" in commits)
+6. Push to your fork
+7. Create PR to upstream
+
+**Branch off `main`** - this is the primary branch.
+
+## Version Management
+
+Update plugin version in `.claude-plugin/plugin.json`:
+
+```json
+{
+  "name": "superpowers",
+  "version": "X.Y.Z",
+  ...
+}
+```
+
+Follow semantic versioning:
+
+- MAJOR: Breaking changes to skill interfaces
+- MINOR: New skills, backward-compatible improvements
+- PATCH: Bug fixes, documentation improvements
+
+## Important Notes
+
+**llm/ Directory:**
+
+- Contains local-only planning documents
+- NOT tracked by git (per `.gitignore`)
+- Safe for scratch notes, implementation plans
+- Do NOT reference these files in skills or commits
+
+**Skill References:**
+
+- Skills are namespace-qualified: `superpowers:skill-name`
+- Use slash commands to activate: `/superpowers:brainstorm`
+- Session hook auto-loads `using-superpowers` at startup
+
+**No Legacy Systems:**
+
+- Skills overlay system removed in v2.0
+- First-party skills system adopted in v3.0
+- No backward compatibility with old skill formats
+
+## Key Reference Files
+
+**Essential reading for contributors:**
+
+- `skills/writing-skills/SKILL.md` - How to create effective skills
+- `skills/using-superpowers/SKILL.md` - How the skills system works
+- `skills/testing-skills-with-subagents/SKILL.md` - Testing methodology
+- `skills/sharing-skills/SKILL.md` - Contributing workflow
+- `README.md` - Installation, quick start, skills overview
+
+**Example skills demonstrating patterns:**
+
+- `skills/systematic-debugging/SKILL.md` - Complex skill with flowchart (Graphviz DOT notation)
+- `skills/condition-based-waiting/` - Skill with supporting TypeScript example
+- `skills/brainstorming/SKILL.md` - Command-activated skill with clear triggers
+
+**Supporting documentation in writing-skills:**
+
+- `anthropic-best-practices.md` - Official Anthropic skill authoring guide
+- `graphviz-conventions.dot` - Flowchart style rules
+- `persuasion-principles.md` - Psychology of effective documentation
+
+## Philosophy
+
+Skills are TDD for documentation. Write tests (baseline runs) first, then write documentation that makes tests pass. Iterate to close loopholes where agents rationalize around requirements. The result: battle-tested process documentation that actually changes agent behavior.

README.md

@@ -14,6 +14,8 @@ Next up, once you say "go", it launches a *subagent-driven-development* process,
 
 There's a bunch more to it, but that's the core of the system. And because the skills trigger automatically, you don't need to do anything special. Your coding agent just has Superpowers.
 
+> **Fork Note:** This is a compatibility-focused fork of [obra/superpowers](https://github.com/obra/superpowers) with production-tested improvements including mechanical enforcement and safety gates. All existing workflows and commands work unchanged. [See what's different →](docs/IMPROVEMENTS.md)
+
 
 ## Sponsorship
 
@@ -110,7 +112,7 @@ Fetch and follow instructions from https://raw.githubusercontent.com/obra/superp
 - **verification-before-completion** - Ensure it's actually fixed
 - **defense-in-depth** - Multiple validation layers
 
-**Collaboration** 
+**Collaboration**
 - **brainstorming** - Socratic design refinement
 - **writing-plans** - Detailed implementation plans
 - **executing-plans** - Batch execution with checkpoints

docs/IMPROVEMENTS.md

@@ -0,0 +1,57 @@
+# Production-Tested Improvements
+
+This fork of [obra/superpowers](https://github.com/obra/superpowers) adds mechanical enforcement and safety gates developed through real-world usage.
+
+## Compatibility
+
+All existing Superpowers workflows, commands, and skills work unchanged. Users familiar with the original can maintain their existing workflows.
+
+## Key Improvements
+
+### 1. Writing-Plans Automation Framework
+
+Enhances the existing `writing-plans` skill with executable wrapper scripts that enforce plan creation through lock files and git pre-commit hooks.
+
+- **Lock file mechanism** ensures plans exist before coding begins
+- **Git pre-commit hooks** prevent commits without corresponding implementation plans
+- **Shifts from documentation to mechanical constraints** - addresses incidents where agents rationalized away requirements
+
+### 2. Automation Over Documentation Framework
+
+A new guidance document establishing when to use code vs. documentation for skill requirements.
+
+- **Clear decision criteria**: objective, programmatically detectable requirements should trigger automation
+- **Reduces documentation churn** - when violations are 100% detectable, use automation
+- **Framework for future skill development** - establishes pattern for similar enforcement needs
+
+### 3. PR Creation Safety Gate
+
+Adds mandatory user preview and approval before pull request creation in the `finishing-a-development-branch` skill.
+
+- **Defense-in-depth approach**: skill-level approval gate + permission rules + system prompts
+- **Preview-then-confirm pattern** prevents bypassing approval workflows through rationalization
+- **Follows pattern from `jira-publisher` skill** - proven safety-critical workflow
+
+### 4. Continuous Execution Pattern
+
+Removes artificial 3-task batching checkpoints from `executing-plans`, allowing uninterrupted workflow through multiple tasks.
+
+- **Improved development velocity** - no artificial pauses
+- **Only genuine blockers cause pauses** - maintains quality gates
+- **Preserves all safety checks** - verification still runs at appropriate times
+
+### 5. Writing-Skills Governance
+
+Strengthens skill modification governance with enhanced discoverability and rationalization counters.
+
+- **Enhanced discoverability** of the writing-skills meta-skill
+- **Rationalization counters** against "just adding a section" shortcuts
+- **Clear guidance on TDD treatment vs. quick updates** - when skills need full testing methodology
+
+## Philosophy
+
+**Automation over documentation** for objective constraints, while preserving judgment-based guidance for subjective decisions. Skills are TDD for documentation—we test first, then write documentation that makes tests pass, iterating to close loopholes where agents rationalize around requirements.
+
+---
+
+[View upstream project](https://github.com/obra/superpowers)

scripts/reload-plugin.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+#
+# reload-plugin.sh - Helper for reloading superpowers plugin in Claude Code
+#
+# This script outputs the slash commands needed to reload the superpowers plugin
+# after making changes. Copy and paste both commands into Claude Code.
+#
+# Usage:
+#   ./scripts/reload-plugin.sh
+#   rls  # if you have the alias set up
+#
+
+# Extract marketplace name from marketplace.json
+MARKETPLACE=$(jq -r '.name' "$(dirname "$0")/../.claude-plugin/marketplace.json" 2>/dev/null || echo "superpowers-dev")
+
+echo "==> Superpowers Plugin Reload Commands"
+echo ""
+echo "Copy and paste these into Claude Code (paste both lines at once):"
+echo ""
+echo "/plugin uninstall superpowers@${MARKETPLACE}"
+echo "/plugin install superpowers@${MARKETPLACE}"
+echo ""
+echo "IMPORTANT: After reload, start a new session to see changes."