[Spec] Audit Skills for Worktree Compatibility, Branch Workflow, and MCP Requirements

[michael-newsrx]

Problem

Three critical gaps in the current skills system:

1. Worktree + Incompatible Tools: When AI agents use worktrees, some MCP tools (PyCharm) don't work because they expect a single workspace, but there's no blocking or warning mechanism.

2. Branch Workflow Inconsistency: Skills don't enforce a consistent branch workflow. Some use <feature-branch>|<main> while this repository uses <feature-branch>|<dev>|<newsrx> (3-branch flow).

3. Missing MCP Handling: Skills that store specs/plans as issues don't check if GitHub/GitBucket MCP is available. If missing, work is lost with no storage mechanism.

Proposed Solution

Comprehensive skill updates to address all three issues with consistent enforcement across the skill system.

Architecture

Core Components

1. Worktree Compatibility Guard - New section in using-git-worktrees/SKILL.md that detects and filters incompatible tools when using worktrees

2. Branch Workflow Configuration - New field in using-superpowers/SKILL.md that parses branch-workflow: feature|dev|<production> from CLAUDE.md/AGENTS.md, plus dynamic detection from origin/HEAD

3. MCP Availability Gate - New section in brainstorming/SKILL.md and writing-plans/SKILL.md that checks MCP before creating specs/plans, halts with clear error if unavailable

4. Branch Enforcement - Updates to all git-touching skills to enforce 3-branch workflow based on configuration

5. Migration Logic - New section in platform-detection.md that discovers existing file-based specs/plans and migrates them to issues

Branch Workflow Configuration

Default Workflow: feature | dev | <production>

Dynamic Branch Detection:

• Detect production branch from git rev-parse --abbrev-ref origin/HEAD
• Fallback to main, then master if remote branches exist
• Halt if cannot detect and no configuration

Branch Initialization:

• Create dev branch from production branch if missing
• If branch-workflow configured in CLAUDE.md/AGENTS.md, use that
• Default is always 3-branch: feature → dev → production

Configuration Format:

## Superpowers Configuration
branch-workflow: feature|dev|newsrx

Worktree Compatibility Guard

Compatible Tools:

• Git commands (worktree-aware)
• File editors (Read, Write, Edit, Bash)
• Language servers (per-file)
• GitHub/GitBucket MCP (API-based, directory-agnostic)

Incompatible Tools (workspace-level state):

• PyCharm MCP - opens project workspace, expects single .idea config
• IDE tools that open projects (VSCode, IntelliJ)
• Any tool maintaining workspace-level sessions/caches

Behavior:

• Detect incompatible tools before worktree creation
• Skip incompatible tools automatically (don't halt)
• Proceed with worktree using compatible tools only
• Report which tools are active vs. skipped after creation

MCP Availability Gate

Location:

• brainstorming/SKILL.md - After user approves design, before creating spec issue
• writing-plans/SKILL.md - After plan written, before creating plan-link comment

Check Logic:

• GIT_PLATFORM=github → GitHub MCP available
• GIT_PLATFORM=gitbucket + GITBUCKET_HAS_CREDENTIALS=true → GitBucket MCP available
• GIT_PLATFORM=unknown or missing credentials → halt

Error Message:

FATAL: Cannot create spec/plan - no issue tracking available

Specs and plans must be tracked in GitHub/GitBucket issues for:
- Persistent storage
- Team visibility
- Progress tracking

Options:
1. Add GitHub remote: git remote add origin https://github.com/user/repo.git
2. Add GitBucket credentials to .env (GITBUCKET_URL, GITBUCKET_TOKEN)
3. Restart session to re-detect platform

Cannot proceed without issue tracking.

Branch Enforcement Across Skills

Skills Updated:

• using-git-worktrees - Create feature branch from integration branch
• finishing-a-development-branch - Merge/PR to integration branch
• brainstorming - Reference correct base branch in spec
• writing-plans - Link plan to spec with correct branches
• subagent-driven-development - Report branch status with workflow context
• executing-plans - Merge work to correct integration branch

Enforcement Pattern:
Each skill reads <GIT_CONTEXT> + branch-workflow config and uses integration branch (not production) for feature work.

Existing File Migration

On Session Start (after platform detected):

If GitHub or GitBucket MCP available:

1. Discover docs/superpowers/specs/*.md and docs/superpowers/plans/*.md
2. For each file:
   • Parse title from markdown header
   • Create issue with proper labels (spec, plan)
   • Move file to docs/superpowers/archive/ after success
3. Report migration summary to dev

Edge Cases:

• No title header → use filename
• Issue already exists → skip
• Archive dir missing → create it
• Migration fails → log error, continue session

Files Modified

• skills/using-git-worktrees/SKILL.md - Add compatible tools section with filtering
• skills/using-superpowers/SKILL.md - Add branch-workflow parsing
• skills/platform-detection.md - Add migration logic + branch detection
• skills/brainstorming/SKILL.md - Add MCP gate before spec creation
• skills/writing-plans/SKILL.md - Add MCP gate before plan creation
• skills/finishing-a-development-branch/SKILL.md - Add branch-workflow enforcement
• Other git-touching skills - Add branch-workflow awareness

Success Criteria

• PyCharm MCP + worktree usage shows warning and proceeds without IDE tools
• Branch workflow defaults to feature|dev|<production> (3-branch)
• dev branch created automatically from production branch if missing
• All git-touching skills use integration branch (not production) for feature work
• Specs/plans cannot be created without GitHub/GitBucket MCP available
• Clear error messages guide devs to fix MCP availability
• Existing file-based specs/plans migrated to issues on first session start
• CLAUDE.md/AGENTS.md can override default branch workflow

[michael-newsrx]

Implementation plan: #4

[michael-newsrx]

Link to follow-up spec for mandatory feature branch enforcement: #6