Skills Audit: Worktree Compatibility, Branch Workflow, MCP Requirements

skills/platform-detection.md

@@ -44,6 +44,158 @@ For GitBucket:
 All specs, plans, and bug reports are stored as issues. No local file fallback.
 ```
 
+## 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 |
+
+## 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.
+
 ## Example: Creating a Spec Issue
 
 ```markdown

skills/using-superpowers/SKILL.md

@@ -39,6 +39,76 @@ If CLAUDE.md, GEMINI.md, or AGENTS.md says "don't use TDD" and a skill says "alw
 
 Skills use Claude Code tool names. Non-CC platforms: see `references/copilot-tools.md` (Copilot CLI), `references/codex-tools.md` (Codex) for tool equivalents. Gemini CLI users get the tool mapping loaded automatically via GEMINI.md.
 
+**See `../platform-detection.md` for details on:**
+- Platform detection (GitHub vs GitBucket)
+- Branch workflow detection and configuration
+- File migration logic
+
+## 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
+
 # Using Skills
 
 ## The Rule