[Spec] Enforce Mandatory Feature Branches and PR Targets

[michael-newsrx]

Problem

During implementation of the previous spec, I violated the workflow I just created:

1. Pushed directly to dev instead of using feature branch
2. Offered PR against newsrx instead of dev
3. No enforcement of mandatory feature branches

This proves the skills are defective - they allow bypassing the workflow.

Root Cause

The previous spec documented the workflow but didn't enforce it:

• using-git-worktrees doesn't enforce feature branch creation
• finishing-a-development-branch doesn't enforce PR target (allows arbitrary selection)
• No flag that feature branches are MANDATORY for this repo

Proposed Fix

1. Add Mandatory Feature Branch Enforcement

In using-git-worktrees:

## Feature Branch Requirement

**MANDATORY:** All work must happen on feature branches. NEVER work directly on:
- Integration branch (dev)
- Production branch (main, master, newsrx)

**Before creating worktree:**
1. Check current branch
2. If on integration or production branch:
   - REQUIRE feature branch creation
   - Block worktree creation until feature branch exists

**Error message:**

FATAL: Cannot work on integration/production branch

Current branch:
Required: Create feature branch first

Run: git checkout -b feature/
Then retry worktree creation

**Feature branch naming:**
- Format: `<prefix>/<feature-name>`
- Default prefix: `feature` (from GIT_WORKFLOW_PREFIX)
- Example: `feature/skills-audit`

2. Enforce PR Target in finishing-a-development-branch

Replace Step 2 with:

### Step 2: Verify Feature Branch and Determine Target

**MANDATORY check:**
```bash
CURRENT_BRANCH=$(git branch --show-current)

# Feature branch format check
if [[ ! "$CURRENT_BRANCH" =~ ^feature/ ]]; then
  echo "FATAL: Not on feature branch"
  echo "Current: $CURRENT_BRANCH"
  echo "Required: feature/<name> branch"
  echo ""
  echo "Create feature branch:"
  echo "  git checkout -b feature/<name> <integration-branch>"
  exit 1
fi

# Get integration branch (PR target)
INTEGRATION_BRANCH=$(grep GIT_INTEGRATION_BRANCH <<< "$GIT_CONTEXT" | cut -d= -f2)

If not in context, detect:

if [ -z "$INTEGRATION_BRANCH" ]; then
  # Check for dev branch
  if git show-ref --verify --quiet refs/heads/dev; then
    INTEGRATION_BRANCH="dev"
  else
    echo "FATAL: Cannot detect integration branch"
    echo "Set GIT_INTEGRATION_BRANCH in <GIT_CONTEXT>"
    exit 1
  fi
fi

PR target is ALWAYS integration branch - no selection allowed.

### 3. Update Step 3 Options

**Remove target selection from options:**

```markdown
### Step 3: Present Options

Present exactly these 4 options:

Implementation complete. What would you like to do?

1. Merge back to locally
2. Push and create a Pull Request against
3. Keep the feature branch as-is (I'll handle it later)
4. Discard this work

Which option?

Options 1 and 2 ALWAYS target <integration-branch>. No user selection.

4. Add Feature Branch Documentation

In using-superpowers Branch Workflow section:

### Feature Branch Requirement

**Feature branches are MANDATORY.** Never commit, merge, or PR directly to:
- Integration branch (default: `dev`)
- Production branch (detected from origin/HEAD)

**Workflow:**
1. Create feature branch from integration branch
2. Work on feature branch only
3. PR against integration branch
4. Integration branch → Production branch (separate workflow)

**Why mandatory:**
- Traceability (each feature is isolated)
- Code review (PRs always from feature branches)
- Parallel work (multiple features don't conflict)
- Integration stability (features tested before merge to dev)

Files to Modify

• skills/using-git-worktrees/SKILL.md - Add mandatory feature branch enforcement
• skills/finishing-a-development-branch/SKILL.md - Enforce PR target, remove selection
• skills/using-superpowers/SKILL.md - Document feature branch requirement
• skills/platform-detection.md - Add feature branch check to session validation (optional)

Success Criteria

• Worktree creation BLOCKED if not on feature branch (or creating one)
• finishing-a-development-branch REQUIRES feature branch format
• PR/merge target is ALWAYS integration branch (no user selection)
• Clear error messages when workflow violated
• Documentation makes feature branch requirement explicit

Priority

HIGH - This defect allowed bypassing the entire workflow during implementation of the workflow itself.