[Plan] Skills Audit: Worktree Compatibility, Branch Workflow, and MCP Requirements

# Skills Audit: Worktree Compatibility, Branch Workflow, and MCP Requirements - Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Update the Superpowers skills system to enforce worktree compatibility, establish a 3-branch workflow default, and gate spec/plan creation on MCP availability.

**Architecture:** Add branch workflow detection and configuration parsing to platform-detection and using-superpowers. Add MCP availability gates to brainstorming and writing-plans skills. Add worktree compatibility filtering to using-git-worktrees. Enforce branch workflow across all git-touching skills. Migrate existing file-based specs/plans to issues.

**Tech Stack:** Git workflow, GitHub/GitBucket MCP tools, Python session init scripts, Markdown skill documentation

---

## File Structure

Each skill file will be updated with focused changes:

- `skills/platform-detection.md` - Branch workflow detection + production branch detection + file migration logic
- `skills/using-superpowers/SKILL.md` - Branch-workflow configuration parsing documentation
- `skills/using-git-worktrees/SKILL.md` - Worktree compatibility guard (compatible/incompatible tools)
- `skills/brainstorming/SKILL.md` - MCP availability gate before spec creation
- `skills/writing-plans/SKILL.md` - MCP availability gate before plan creation
- `skills/finishing-a-development-branch/SKILL.md` - Branch workflow enforcement (use integration branch)

---

### Task 1: Platform Detection - Branch Workflow Detection

**Files:**
- Modify: `skills/platform-detection.md:1-114`

**Goal:** Detect production branch from git remote metadata and create integration branch if missing.

- [ ] **Step 1: Add branch detection section to platform-detection.md**

Add after the existing "Label Requirements" section (line ~72):

```markdown
## Branch Workflow Detection

**Automatic at session start:**

The plugin detects and configures the branch workflow:

1. **Detect production branch:**
   ```bash
   # Try origin/HEAD first
   PRODUCTION_BRANCH=$(git rev-parse --abbrev-ref origin/HEAD 2>/dev/null | sed 's|origin/||')
   
   # Fallback to common names
   if [ -z "$PRODUCTION_BRANCH" ]; then
     for branch in main master; do
       if git show-ref --verify --quiet refs/remotes/origin/$branch; then
         PRODUCTION_BRANCH=$branch
         break
       fi
     done
   fi
   ```

2. **If production branch cannot be detected:**
   - Halt session with error: "Cannot detect production branch. Set origin/HEAD with: `git remote set-head origin <your-main-branch>`"
   - Suggest adding `branch-workflow: feature|dev|<branch>` to CLAUDE.md or AGENTS.md

3. **Read branch-workflow configuration:**
   - Parse CLAUDE.md/AGENTS.md for `branch-workflow: <prefix>|<integration>|<production>`
   - Format: `<feature-prefix>|<integration-branch>|<production-branch>`
   - Example: `branch-workflow: feature|dev|newsrx`

4. **Default workflow:**
   - If no configuration: use `feature|dev|<PRODUCTION_BRANCH>`
   - Feature prefix: `feature` (or configured prefix)
   - Integration branch: `dev` (or configured integration branch)
   - Production branch: detected from origin/HEAD or configuration

5. **Create integration branch if missing:**
   ```bash
   INTEGRATION_BRANCH="dev"  # default
   CONFIGURED_WORKFLOW=$(grep "branch-workflow:" CLAUDE.md AGENTS.md 2>/dev/null)
   
   if [ -n "$CONFIGURED_WORKFLOW" ]; then
     INTEGRATION_BRANCH=$(echo "$CONFIGURED_WORKFLOW" | cut -d'|' -f2)
   fi
   
   # Create if missing
   if ! git show-ref --verify --quiet refs/heads/$INTEGRATION_BRANCH; then
     if [ -n "$PRODUCTION_BRANCH" ]; then
       git branch $INTEGRATION_BRANCH $PRODUCTION_BRANCH
       echo "Created '$INTEGRATION_BRANCH' branch from '$PRODUCTION_BRANCH'"
       # Push to remote if origin exists
       git push -u origin $INTEGRATION_BRANCH 2>/dev/null || true
     fi
   fi
   ```

6. **Inject into session context:**
   ```
   <GIT_CONTEXT>
   ...
   GIT_WORKFLOW_PREFIX=feature
   GIT_INTEGRATION_BRANCH=dev
   GIT_PRODUCTION_BRANCH=<detected>
   </GIT_CONTEXT>
   ```

**Examples:**

| Repo State | Detection Result |
|-----------|------------------|
| origin/HEAD set | Production branch from origin/HEAD |
| No origin/HEAD, has origin/main | Production = main |
| No origin/HEAD, has origin/master | Production = master |
| Custom main branch (newsrx) | If origin/HEAD → origin/newsrx, detected correctly |
| No remote branches | Halt with error, suggest configuration |
```

- [ ] **Step 2: Verify markdown renders correctly**

Run: Read the file to check formatting:
```
The new section should appear after "Label Requirements" and before "Example: Creating a Spec Issue"
```

- [ ] **Step 3: Commit**

```bash
git add skills/platform-detection.md
git commit -m "feat(platform-detection): add branch workflow detection and production branch discovery"
```

---

### Task 2: Platform Detection - File Migration Logic

**Files:**
- Modify: `skills/platform-detection.md`

**Goal:** Migrate existing file-based specs and plans to GitHub/GitBucket issues on session start.

- [ ] **Step 1: Add migration section to platform-detection.md**

Add after the new "Branch Workflow Detection" section:

```markdown
## File Migration to Issues

**On session start (after platform detected):**

If GitHub or GitBucket MCP available:

1. **Discover existing files:**
   ```bash
   find docs/superpowers/specs -name "*.md" -type f 2>/dev/null
   find docs/superpowers/plans -name "*.md" -type f 2>/dev/null
   ```

2. **For each spec file:**
   ```markdown
   If GIT_PLATFORM=github:
     - Parse title from first `# ` header
     - Use github_issue_write with:
       - title: `[Spec] <parsed-title>`
       - body: File content + "\n\nMigrated from: `docs/superpowers/specs/<filename>.md`"
       - labels: spec
   
   If GIT_PLATFORM=gitbucket:
     - Parse title from first `# ` header
     - Use gitbucket_create_issue with:
       - title: `[Spec] <parsed-title>`
       - body: File content + "\n\nMigrated from: `docs/superpowers/specs/<filename>.md`"
       - labels: spec
   ```

3. **For each plan file:**
   ```markdown
   If GIT_PLATFORM=github:
     - Parse title from first `# ` header
     - Use github_issue_write with:
       - title: `[Plan] <parsed-title>`
       - body: File content + "\n\nMigrated from: `docs/superpowers/plans/<filename>.md`"
       - labels: plan
   
   If GIT_PLATFORM=gitbucket:
     - Parse title from first `# ` header
     - Use gitbucket_create_issue with:
       - title: `[Plan] <parsed-title>`
       - body: File content + "\n\nMigrated from: `docs/superpowers/plans/<filename>.md`"
       - labels: plan
   ```

4. **On successful issue creation:**
   ```bash
   # Create archive directory if missing
   mkdir -p docs/superpowers/archive
   
   # Move file to archive
   mv docs/superpowers/specs/<filename>.md docs/superpowers/archive/<filename>.md
   ```

5. **Add archive comment to issue:**
   ```markdown
   Add comment: "Archived original: `docs/superpowers/archive/<filename>.md`"
   ```

6. **Report to dev:**
   ```
   Migrated <N> specs, <M> plans to GitHub/GitBucket issues.
   Originals archived in docs/superpowers/archive/
   ```

**Error handling:**
- File has no title header → use filename as title
- Issue already exists (title match) → skip, don't duplicate
- Archive directory missing → create it
- Migration fails → log error, continue session, leave file in place
- Platform unknown → skip migration (file-based workflow continues)

**Migration runs once:** Only on first session start after MCP available.
```

- [ ] **Step 2: Verify the migration logic is clear**

Read through the section to ensure the workflow is complete:
```
- Discovery → Creation → Archival → Reporting
- All error cases covered
- GitHub and GitBucket paths defined
```

- [ ] **Step 3: Commit**

```bash
git add skills/platform-detection.md
git commit -m "feat(platform-detection): add file migration logic for specs and plans to issues"
```

---

### Task 3: Branch Workflow Configuration Parsing

**Files:**
- Modify: `skills/using-superpowers/SKILL.md:40-113`

**Goal:** Document how skills should read branch-workflow configuration from GIT_CONTEXT.

- [ ] **Step 1: Add branch workflow configuration documentation**

Add new section after "Platform Adaptation" (line ~38):

```markdown
## Branch Workflow Configuration

Skills that create branches, merge, or create PRs MUST read branch workflow from `<GIT_CONTEXT>`.

### Reading Branch Workflow

**From session context:**
```
<GIT_CONTEXT>
...
GIT_WORKFLOW_PREFIX=feature
GIT_INTEGRATION_BRANCH=dev
GIT_PRODUCTION_BRANCH=<detected>
</GIT_CONTEXT>
```

**Three-branch workflow (default):**
- Feature branches branch from integration branch (`dev`)
- Feature branches merge/PR back to integration branch
- Integration branch eventually merges to production branch

**Two-branch workflow (when configured):**
- Feature branches branch from production branch
- Feature branches merge/PR back to production branch

### Overriding Default

Users can override in CLAUDE.md or AGENTS.md:

```markdown
## Superpowers Configuration

branch-workflow: feature|dev|newsrx
```

Format: `<prefix>|<integration>|<production>`

### Skill Integration Pattern

```markdown
When creating a feature branch:
1. Read GIT_INTEGRATION_BRANCH from <GIT_CONTEXT>
2. Use it as base: `git worktree add .worktrees/feature-name -b feature-name $INTEGRATION_BRANCH`

When merging/PR:
1. Read GIT_INTEGRATION_BRANCH from <GIT_CONTEXT>
2. Use it as target: `git checkout $INTEGRATION_BRANCH && git merge feature-name`
3. Or create PR against $INTEGRATION_BRANCH

When referencing branches in issues:
- Spec: "Feature will integrate into `<integration-branch>` branch"
- PR: Create PR against integration branch (not production)
```

### Skills That Must Enforce

All git-touching skills must read and respect branch workflow:

- `using-git-worktrees` - Creates feature branch from integration branch
- `finishing-a-development-branch` - Merges/PRs to integration branch
- `brainstorming` - References correct base branch in spec
- `writing-plans` - Links plan to spec with correct branches
- `subagent-driven-development` - Reports branch status with workflow context
- `executing-plans` - Merges work to correct integration branch
```

- [ ] **Step 2: Update existing platform detection reference**

The existing "Platform Detection" section references `../platform-detection.md`. Add a note that this file also configures branch workflow:

```markdown
## Platform Detection

Skills that interact with issue tracking, specs, and plans must detect which platform is available and adapt accordingly.

See `../platform-detection.md` for details on:
- Platform detection (GitHub vs GitBucket)
- Branch workflow detection and configuration
- File migration logic
```

- [ ] **Step 3: Commit**

```bash
git add skills/using-superpowers/SKILL.md
git commit -m "feat(using-superpowers): document branch workflow configuration parsing"
```

---

### Task 4: Worktree Compatibility Guard

**Files:**
- Modify: `skills/using-git-worktrees/SKILL.md`

**Goal:** Filter incompatible tools when using worktrees.

- [ ] **Step 1: Add worktree compatibility section**

Add new section after "Integration" section (line ~209):

```markdown
## Worktree Compatibility Guard

**When using worktrees:**
Some MCP tools expect a single workspace and don't work correctly with worktrees.

### Compatible Tools

**These tools work in worktrees:**
- Git commands (worktree-aware, operate on `.git` directory)
- File editors (Read, Write, Edit, Bash)
- Language servers (operate per-file)
- GitHub MCP tools (API-based, directory-agnostic)
- GitBucket MCP tools (API-based, directory-agnostic)

### Incompatible Tools (Workspace-Level State)

**These tools expect single workspace:**
- PyCharm MCP - opens project workspace, expects single `.idea` config
- IDE tools that open projects (VSCode extensions, IntelliJ tools)
- Any tool maintaining workspace-level sessions or caches

### Detection and Filtering

**Before creating worktree:**

```markdown
Check available MCP tools in session:
- If PyCharm_* tools detected → WARN and SKIP these tools
- If any tool with open_workspace, load_project patterns → WARN and SKIP

**Warning message:**
```
PyCharm MCP tools detected but incompatible with worktrees.

Continuing with Git/File/GitHub/GitBucket tools only. IDE features will not be available in worktree.

Proceeding with worktree creation...
```
```

**After worktree created:**

```markdown
Report compatibility status:
```
Worktree ready at <worktree-path>
Using: Git, File, GitHub/GitBucket MCP tools
Skipped: PyCharm MCP (incompatible with worktrees)

For IDE features, use main workspace at <main-workspace-path>
```
```

### Implementation

In `platform-detection.md`, inject tool compatibility into `<GIT_CONTEXT>`:

```
<GIT_CONTEXT>
...
WORKTREE_COMPATIBLE_TOOLS=git,file,bash,github-mcp,gitbucket-mcp
WORKTREE_INCOMPATIBLE_TOOLS=pycharm-mcp
</GIT_CONTEXT>
```

Skills check this before using worktrees and filter tool usage accordingly.

### Why Not Block

**Incompatible tools are filtered, not blocked:**
- Blocking halts work unnecessarily
- Many workflows succeed with Git/File tools alone
- Dev can still use IDE features in main workspace
- Clear messaging informs dev of limitations

**Proceed with partial functionality** vs. **Stop everything**.
```

- [ ] **Step 2: Verify all sections reference the filtering correctly**

Read through the skill to ensure the compatibility guard is mentioned where needed:
```
- "Integration" section should mention this is called by other skills
- Creation steps should reference compatibility check
```

- [ ] **Step 3: Commit**

```bash
git add skills/using-git-worktrees/SKILL.md
git commit -m "feat(using-git-worktrees): add worktree compatibility guard with tool filtering"
```

---

### Task 5: Brainstorming MCP Gate

**Files:**
- Modify: `skills/brainstorming/SKILL.md:109-139`

**Goal:** Gate spec creation on MCP availability, halt if unavailable.

- [ ] **Step 1: Update the "Create Spec Issue" section**

Replace the existing "Create Spec Issue (REQUIRED)" section (lines ~109-139) with:

```markdown
**Create Spec Issue (REQUIRED):**

Specs are stored as GitHub/GitBucket issues. No local file storage.

**MCP Availability Gate (BEFORE creating issue):**

Check `<GIT_CONTEXT>` for MCP availability:

```
If GIT_PLATFORM=github:
  GitHub MCP available → Proceed with github_issue_write

If GIT_PLATFORM=gitbucket:
  If GITBUCKET_HAS_CREDENTIALS=false:
    STOP. Tell user: "GitBucket credentials required. Set GITBUCKET_URL and GITBUCKET_TOKEN in .env, then restart session."
    Do not proceed until credentials configured.
  
  GitBucket MCP available → Proceed with gitbucket_create_issue

If GIT_PLATFORM=unknown:
  STOP. Tell user:
  ```
  FATAL: Cannot create spec - 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.
  ```
  Do not proceed until platform is configured.
```

**Create Issue (after gate passes):**

```markdown
If GIT_PLATFORM=github:
  Use github_issue_write with:
  - method: "create"
  - title: [Spec] <topic>
  - body: Full design specification (all sections, complete content)
  - labels: spec, plus relevant feature labels

If GIT_PLATFORM=gitbucket:
  Use gitbucket_create_issue with:
  - title: [Spec] <topic>
  - body: Full design specification (all sections, complete content)
  - labels: spec, plus relevant feature labels
```

**Why Halt Instead of Fallback:**

File-based specs are **not acceptable** because:
- No team visibility
- No persistent tracking
- Lost on developer machine
- No integration with workflow

**MCP availability is a hard requirement.** Halt with clear remediation steps.
```

- [ ] **Step 2: Verify the gate appears before any spec creation logic**

Read through to ensure the gate check happens before `github_issue_write` or `gitbucket_create_issue`:

```
The MCP availability check should be the FIRST thing in this section.
```

- [ ] **Step 3: Commit**

```bash
git add skills/brainstorming/SKILL.md
git commit -m "feat(brainstorming): add MCP availability gate before spec creation"
```

---

### Task 6: Writing Plans MCP Gate

**Files:**
- Modify: `skills/writing-plans/SKILL.md:125-155`

**Goal:** Gate plan creation on MCP availability, halt if unavailable.

- [ ] **Step 1: Update the "After the Plan" section**

Replace the existing "Create Plan Issue" subsection (lines ~125-155) with:

```markdown
## After the Plan

**Create Plan Issue (REQUIRED):**

Plans are stored as GitHub/GitBucket issues. No local file storage.

**MCP Availability Gate (BEFORE creating issue):**

Check `GIT_PLATFORM` in your session context (`<GIT_CONTEXT>` block):

- If `GIT_PLATFORM=github`:
  - GitHub MCP available → Proceed with github_issue_write

- Else if `GIT_PLATFORM=gitbucket`:
  ```markdown
  Check GITBUCKET_HAS_CREDENTIALS:
  - If false: STOP. Tell user "GitBucket credentials required. Set GITBUCKET_URL and GITBUCKET_TOKEN in .env, then restart session."
  - If true: Proceed with gitbucket_create_issue
  ```

- Else (unknown):
  ```markdown
  STOP. Tell user:
  ```
  FATAL: Cannot create plan - no issue tracking available
  
  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.
  ```
  ```

**Create Plan Issue (after gate passes):**

The issue body should contain the complete plan with:
- All tasks
- All steps
- Complete code blocks

Use the following:

- If GitHub:
  ```markdown
  Use github_issue_write with:
  - method: "create"
  - title: [Plan] <feature-name> Implementation
  - body: Full implementation plan (all sections, complete content)
  - labels: plan
  ```

- If GitBucket:
  ```markdown
  Use gitbucket_create_issue with:
  - title: [Plan] <feature-name> Implementation
  - body: Full implementation plan (all sections, complete content)
  - labels: plan
  ```

**Link to Spec Issue:**

Comment on the spec issue to link this plan:

- If GitHub: `github_add_issue_comment(spec_issue_number, "Implementation plan: #<plan_issue_number>")`
- If GitBucket: `gitbucket_add_issue_comment(spec_issue_number, "Implementation plan: #<plan_issue_number>")`

**No Local File Storage:**

Plans are NOT stored in `docs/superpowers/plans/`. They live only as issues.

**Why Halt Instead of Fallback:**

File-based plans are **not acceptable** because:
- No team visibility
- No persistent tracking
- Lost on developer machine
- No integration with workflow

**MCP availability is a hard requirement.** Halt with clear remediation steps.
```

- [ ] **Step 2: Verify the gate appears before plan creation**

Read through to ensure:
```
- Gate check before github_issue_write or gitbucket_create_issue
- No mention of local file storage (docs/superpowers/plans/)
- Link to spec issue happens after plan creation
```

- [ ] **Step 3: Commit**

```bash
git add skills/writing-plans/SKILL.md
git commit -m "feat(writing-plans): add MCP availability gate before plan creation"
```

---

### Task 7: Finishing Branch Workflow Enforcement

**Files:**
- Modify: `skills/finishing-a-development-branch/SKILL.md:40-50`

**Goal:** Enforce branch workflow - use integration branch as base for merge/PR.

- [ ] **Step 1: Update "Determine Base Branch" section**

Replace lines ~40-50 with:

```markdown
### Step 2: Determine Target Branch

**Read branch workflow from session:**

```markdown
Parse <GIT_CONTEXT> for:
- GIT_INTEGRATION_BRANCH (e.g., "dev")
- GIT_PRODUCTION_BRANCH (e.g., "main", "newsrx")
```

```bash
# Use integration branch as target for feature work
INTEGRATION_BRANCH=$(grep GIT_INTEGRATION_BRANCH <<< "$GIT_CONTEXT" | cut -d= -f2)

# Verify branch exists
git show-ref --verify --quiet refs/heads/$INTEGRATION_BRANCH

# Or detect from git if not in context
if [ -z "$INTEGRATION_BRANCH" ]; then
  # Check for dev branch
  if git show-ref --verify --quiet refs/heads/dev; then
    INTEGRATION_BRANCH="dev"
  else
    # Fallback to production branch
    INTEGRATION_BRANCH=$(git rev-parse --abbrev-ref origin/HEAD | sed 's|origin/||')
  fi
fi
```

**Ask if unclear:**
```
This branch appears to integrate into '$INTEGRATION_BRANCH'. Is that correct?

1. Yes, merge to $INTEGRATION_BRANCH
2. No, merge to different branch (specify)

Which option?
```

### Step 3: Present Options

Present exactly these 4 options:

```
Implementation complete. What would you like to do?

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

Which option?
```

**Don't add explanation** - keep options concise.
```

- [ ] **Step 2: Update "Merge Locally" and "Push and Create PR" sections**

Update line ~70 (Option 1: Merge Locally):

```markdown
#### Option 1: Merge Locally

```bash
# Switch to integration branch
git checkout $INTEGRATION_BRANCH

# Pull latest
git pull

# Merge feature branch
git merge <feature-branch>

# Verify tests on merged result
<test command>

# If tests pass
git branch -d <feature-branch>
```

Then: Cleanup worktree (Step 5)
```

Update line ~89 (Option 2: Push and Create PR):

```markdown
#### Option 2: Push and Create PR

```bash
# Push branch
git push -u origin <feature-branch>

# Create PR against integration branch
gh pr create --base $INTEGRATION_BRANCH --title "<title>" --body "$(cat <<'EOF'
## Summary
<2-3 bullets of what changed>

## Test Plan
- [ ] <verification steps>
EOF
)"
```

Then: Cleanup worktree (Step 5)
```

- [ ] **Step 3: Verify all git operations use integration branch**

Read through the entire skill to ensure:
```
- Integration branch is used for checkout, merge, and PR base
- Production branch is NOT used for feature work
- Branch workflow is documented in integration section
```

- [ ] **Step 4: Commit**

```bash
git add skills/finishing-a-development-branch/SKILL.md
git commit -m "feat(finishing-a-development-branch): enforce branch workflow with integration branch"
```

---

### Task 8: Test Complete Workflow

**Goal:** Verify all components work together.

- [ ] **Step 1: Review file changes**

Verify all modified files:
```bash
git log --oneline --all
```

Expected commits:
1. feat(platform-detection): add branch workflow detection
2. feat(platform-detection): add file migration logic
3. feat(using-superpowers): document branch workflow configuration
4. feat(using-git-worktrees): add worktree compatibility guard
5. feat(brainstorming): add MCP availability gate
6. feat(writing-plans): add MCP availability gate
7. feat(finishing-a-development-branch): enforce branch workflow

- [ ] **Step 2: Verify integration points**

Check each integration point manually:

1. **Branch Workflow Detection:**
   - platform-detection.md has branch detection logic
   - using-superpowers/SKILL.md documents GIT_CONTEXT reading
   - finishing-a-development-branch uses integration branch

2. **Worktree Compatibility:**
   - using-git-worktrees filters incompatible tools
   - Warning messages are clear
   - Proceed logic is documented

3. **MCP Gates:**
   - brainstorming halts without MCP
   - writing-plans halts without MCP
   - Clear error messages guide devs

4. **File Migration:**
   - platform-detection.md has migration logic
   - GitHub and GitBucket paths defined
   - Archive mechanism documented

- [ ] **Step 3: Final verification of spec requirements**

Go through the spec issue #3 success criteria:

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

All criteria met.

---

## Self-Review Checklist

1. **Spec coverage:** Each requirement from spec issue #3 has a corresponding task
2. **Placeholder scan:** No TBD, TODO, or incomplete sections
3. **Type consistency:** Branch workflow terms (integration, production, feature) used consistently
4. **File paths:** All file paths are exact
5. **Code blocks:** All code changes shown in full
6. **Commits:** Each task has clear commit message

Navigation Menu

Uh oh!

[Plan] Skills Audit: Worktree Compatibility, Branch Workflow, and MCP Requirements #4

Skills Audit: Worktree Compatibility, Branch Workflow, and MCP Requirements - Implementation Plan

File Structure

Task 1: Platform Detection - Branch Workflow Detection

Task 2: Platform Detection - File Migration Logic

Task 3: Branch Workflow Configuration Parsing

Skill Integration Pattern

Skills That Must Enforce

Task 4: Worktree Compatibility Guard

Implementation

Why Not Block

Task 5: Brainstorming MCP Gate

Task 6: Writing Plans MCP Gate

Task 7: Finishing Branch Workflow Enforcement

Step 3: Present Options

Task 8: Test Complete Workflow

Self-Review Checklist

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Repo State	Detection Result
origin/HEAD set	Production branch from origin/HEAD
No origin/HEAD, has origin/main	Production = main
No origin/HEAD, has origin/master	Production = master
Custom main branch (newsrx)	If origin/HEAD → origin/newsrx, detected correctly
No remote branches	Halt with error, suggest configuration

Uh oh!

[Plan] Skills Audit: Worktree Compatibility, Branch Workflow, and MCP Requirements #4

Description

Skills Audit: Worktree Compatibility, Branch Workflow, and MCP Requirements - Implementation Plan

File Structure

Task 1: Platform Detection - Branch Workflow Detection

Task 2: Platform Detection - File Migration Logic

Task 3: Branch Workflow Configuration Parsing

Skill Integration Pattern

Skills That Must Enforce

Task 4: Worktree Compatibility Guard

Implementation

Why Not Block

Task 5: Brainstorming MCP Gate

Task 6: Writing Plans MCP Gate

Task 7: Finishing Branch Workflow Enforcement

Step 3: Present Options

Task 8: Test Complete Workflow

Self-Review Checklist

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions