diff --git a/skills/platform-detection.md b/skills/platform-detection.md index c7756feaf3..1bf3bcc351 100644 --- a/skills/platform-detection.md +++ b/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 `" + - Suggest adding `branch-workflow: feature|dev|` to CLAUDE.md or AGENTS.md + +3. **Read branch-workflow configuration:** + - Parse CLAUDE.md/AGENTS.md for `branch-workflow: ||` + - Format: `||` + - Example: `branch-workflow: feature|dev|newsrx` + +4. **Default workflow:** + - If no configuration: use `feature|dev|` + - 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_WORKFLOW_PREFIX=feature + GIT_INTEGRATION_BRANCH=dev + GIT_PRODUCTION_BRANCH= + + ``` + +**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] ` + - body: File content + "\n\nMigrated from: `docs/superpowers/specs/.md`" + - labels: spec + + If GIT_PLATFORM=gitbucket: + - Parse title from first `# ` header + - Use gitbucket_create_issue with: + - title: `[Spec] ` + - body: File content + "\n\nMigrated from: `docs/superpowers/specs/.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] ` + - body: File content + "\n\nMigrated from: `docs/superpowers/plans/.md`" + - labels: plan + + If GIT_PLATFORM=gitbucket: + - Parse title from first `# ` header + - Use gitbucket_create_issue with: + - title: `[Plan] ` + - body: File content + "\n\nMigrated from: `docs/superpowers/plans/.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/.md docs/superpowers/archive/.md + ``` + +5. **Add archive comment to issue:** + ```markdown + Add comment: "Archived original: `docs/superpowers/archive/.md`" + ``` + +6. **Report to dev:** + ``` + Migrated specs, 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 diff --git a/skills/using-superpowers/SKILL.md b/skills/using-superpowers/SKILL.md index c8a857024b..a92183a878 100644 --- a/skills/using-superpowers/SKILL.md +++ b/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 ``. + +### Reading Branch Workflow + +**From session context:** +``` + +... +GIT_WORKFLOW_PREFIX=feature +GIT_INTEGRATION_BRANCH=dev +GIT_PRODUCTION_BRANCH= + +``` + +**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: `||` + +### Skill Integration Pattern + +```markdown +When creating a feature branch: +1. Read GIT_INTEGRATION_BRANCH from +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 +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 `` 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