hub-launch 1.0.3

package/dist/templates/skills/hula-merge/SKILL.md

@@ -0,0 +1,387 @@
+---
+name: hula-merge
+description: Merge a PR — handles both local worktree and remote-only branches. Use when the user asks to merge, complete, or close a PR.
+disable-model-invocation: true
+argument-hint: "[issue-number]"
+allowed-tools: Bash Read
+---
+
+You are an expert PR merger for the HubLaunch project. You handle two scenarios automatically:
+
+- **Local session merge**: A `/hula-fix` session exists with a local worktree — commit, push, merge, then clean up.
+- **Remote-only merge**: No local session/worktree (e.g. PR was created by GitHub Copilot coding agent, another contributor, or a previous session was cleaned up) — merge the PR directly via GitHub.
+
+You detect which path to take automatically. The user never needs to specify.
+
+## Instructions
+
+Your job is to:
+
+1. **Detect merge path** — check for local fix session + worktree, or fall back to remote-only
+2. **If local session exists**: commit/push changes, merge PR, clean up worktree + session
+3. **If remote-only**: merge PR directly via `hula merge`
+4. **Report results**
+
+The main working tree is **never modified** — all local operations happen in the fix worktree (if one exists).
+
+User input: $ARGUMENTS
+
+## Workflow
+
+### Step 1: Determine Issue Number
+
+**Priority 1: Check chat history**
+
+- Look for `<!-- hula-fix-session: {...} -->` from previous `/hula-fix` command
+- Parse JSON to get: `issueNumber`, `worktreePath`, `prBranch`
+
+**Priority 2: Check user input**
+
+- Look for explicit issue number in the `/hula-merge` invocation (e.g. `/hula-merge 42` or `/hula-merge #42`)
+- Look for pattern: `YizYah/<repo>#\d+` or `#\d+` in user input
+
+**Priority 3: Check tracked issues**
+
+- Run `hula view` to list tracked issues
+- If only one tracked issue has an open PR, use it automatically
+- If multiple, ask user to select
+
+**If no issue found**:
+
+```
+❌ No issue number found.
+
+Usage:
+- /hula-merge (auto-detect from fix session or tracked issues)
+- /hula-merge 42 (explicit issue number)
+```
+
+Stop execution here. Do not proceed.
+
+### Step 2: Detect Merge Path
+
+Once you have the issue number, determine which merge path to use:
+
+**Check 1: Look for session file**
+
+- Check if `.hublaunch/.fix-sessions/issue-<N>.json` exists
+- If found, parse it to get `worktreePath` and `prBranch`
+
+**Check 2: Verify worktree exists (only if session was found)**
+
+```bash
+git worktree list --porcelain | grep "<worktreePath>"
+```
+
+**Decision logic:**
+
+| Session file exists? | Worktree exists? | Path                                                   |
+| -------------------- | ---------------- | ------------------------------------------------------ |
+| Yes                  | Yes              | **Path A: Local session merge**                        |
+| Yes                  | No               | **Path B: Remote-only merge** (clean up stale session) |
+| No                   | N/A              | **Path B: Remote-only merge**                          |
+
+Display the detected path:
+
+- Path A: `ℹ️  Local fix session found — will commit, push, merge, and clean up worktree.`
+- Path B: `ℹ️  No local session — will merge PR directly on GitHub.`
+
+---
+
+## Path A: Local Session Merge
+
+Follow this path when a fix session AND its worktree both exist.
+
+### Step A1: Check for Changes in Worktree
+
+Run inside the worktree:
+
+```bash
+cd <worktreePath>
+git status --porcelain
+```
+
+**If output is empty**: skip Step A2, proceed directly to Step A3 (the script handles the no-changes case gracefully).
+
+Display: "ℹ️ No changes to commit, proceeding to merge..."
+
+**If output has changes**: proceed to Step A2.
+
+### Step A2: Ask About Running Tests
+
+Detect test command from `package.json` (look for: `test`, `typecheck`, `lint`).
+
+```
+You have uncommitted changes ready to commit.
+
+Would you like to run tests before pushing? (y/n)
+
+Suggested test command: npm test
+```
+
+**If yes**: run tests inside the worktree (`cd <worktreePath> && npm test`).
+
+- If tests fail: show error and ask if they want to proceed anyway.
+
+**If no**: proceed to Step A3.
+
+### Step A3: Commit, Push, Merge, and Clean Up (Script)
+
+Generate a commit message based on the issue number, files changed, and nature of changes, then run the local-merge script — it handles commit, push, merge, worktree removal, and session cleanup in one terminal approval:
+
+```bash
+bash .github/scripts/hula-merge-local.sh <issue-number> "<worktreePath>" "fix(#42): <generated-message>"
+```
+
+The script outputs JSON with `status`, `committed`, `filesChanged`, `worktreeRemoved`, and `sessionCleaned`.
+
+Parse the JSON output:
+- If `status` is `"error"`, display the `message` and stop. The session is preserved so you can retry.
+- If `status` is `"success"`, proceed to Step A4.
+
+Display based on output:
+- If `committed` is `true`:
+  ```
+  ✅ Changes committed: "<commitMessage>"
+  🚀 Pushed to remote
+  ```
+- If `filesChanged` is `0`:
+  ```
+  ℹ️  No changes to commit, proceeding to merge...
+  ```
+- Always display:
+  ```
+  🔀 Merged PR for issue #42 ✅
+  🧹 Removed fix worktree: <worktreePath>
+  🧹 Cleaned up session file
+  ```
+
+### Step A4: Delete Local Branch
+
+After the script completes successfully, delete the local branch:
+
+```bash
+git branch -D <prBranch>
+```
+
+- If the above fails (branch still held by worktree ref), it was removed with the worktree — skip silently.
+
+Display:
+
+```
+🧹 Deleted local branch: <prBranch>
+```
+
+Or if already gone:
+
+```
+ℹ️  Local branch already removed with worktree
+```
+
+### Step A5: Success Summary
+
+```
+✨ Merge completed successfully!
+
+Summary:
+- Committed and pushed changes from worktree ✅
+- Merged PR for issue #42 ✅
+- Closed issue #42 ✅
+- Removed fix worktree ✅
+- Deleted local branch: <prBranch> ✅
+
+Main working tree was never modified. You're ready for the next task!
+```
+
+---
+
+## Path B: Remote-Only Merge
+
+Follow this path when no local fix session/worktree exists. This is the common path when:
+
+- GitHub Copilot coding agent created and worked on the PR
+- Another contributor submitted the PR
+- A previous `/hula-fix` session was already cleaned up
+- The user ran `/hula-create` with Copilot assignment
+
+### Step B1: Remote-Only Merge and Cleanup (Script)
+
+Run the remote-merge script — it merges the PR directly on GitHub and cleans up any stale session file in one terminal approval:
+
+```bash
+bash .github/scripts/hula-merge-remote.sh <issue-number>
+```
+
+The script outputs JSON with `status`, `issueNumber`, and `sessionCleaned`.
+
+Parse the JSON output:
+- If `status` is `"error"`, display the `message` and stop.
+- If `status` is `"success"`, proceed to Step B2.
+
+Display:
+- If `sessionCleaned` is `true`: `🧹 Cleaned up stale session file`
+
+### Step B2: Delete Local Branch (if applicable)
+
+Check whether the branch exists locally:
+
+```bash
+git branch --list <prBranch>
+```
+
+**If the branch exists locally:**
+
+1. Check current branch:
+   ```bash
+   git rev-parse --abbrev-ref HEAD
+   ```
+2. If currently on the branch, detect default branch and switch first:
+   ```bash
+   gh repo view --json defaultBranchRef --jq ".defaultBranchRef.name"
+   git checkout <defaultBranch>
+   ```
+3. Delete the local branch:
+   ```bash
+   git branch -D <prBranch>
+   ```
+   Display: `🧹 Deleted local branch: <prBranch>`
+
+**If the branch does not exist locally:**
+
+Display: `ℹ️  No local branch to clean up`
+
+### Step B3: Success Summary
+
+```
+✨ Merge completed successfully!
+
+Summary:
+- Merged PR for issue #42 on GitHub ✅
+- Closed issue #42 ✅
+- Deleted local branch: <prBranch> ✅  (or: No local branch to clean up)
+
+No local worktree was involved — PR was merged directly on GitHub.
+```
+
+---
+
+## Error Handling
+
+### Merge Conflicts
+
+```
+❌ Merge conflict detected!
+
+The PR has conflicts with the base branch.
+
+Options:
+1. Resolve conflicts via GitHub PR web UI
+2. If local worktree exists: resolve in worktree at <worktreePath>
+3. Run /hula-merge again after resolving
+```
+
+### CI Checks Failing
+
+```
+⚠️  CI checks are failing for this PR.
+
+Failing checks: <list>
+
+Options:
+1. Wait for checks to pass
+2. Investigate failures on GitHub
+3. Proceed anyway? (y/n)
+```
+
+### Commit Fails (Path A only)
+
+```
+❌ Failed to commit changes: <error>
+
+Ensure git user.name and user.email are configured.
+```
+
+### Push Fails (Path A only)
+
+```
+❌ Failed to push changes: <error>
+
+Try: cd <worktreePath> && git push
+```
+
+### Merge Command Fails
+
+```
+❌ Failed to merge PR: <error>
+
+Check the PR on GitHub: <PR-URL>
+```
+
+For Path A: `Session preserved — run /hula-merge again after resolving.`
+For Path B: `Run /hula-merge again after resolving.`
+
+## Important Notes
+
+### Adaptive Path Detection
+
+The merge command automatically detects whether to use the local worktree path or remote-only path. Users do not need to specify which mode to use. The detection is based on:
+
+1. Presence of `.hublaunch/.fix-sessions/issue-<N>.json`
+2. Whether the worktree at the recorded path still exists
+
+This covers all scenarios:
+
+- `/hula-fix` → `/hula-merge` on the same machine (Path A)
+- Copilot coding agent created the PR on GitHub (Path B)
+- Another contributor's PR (Path B)
+- Previous fix session already cleaned up (Path B)
+
+### Worktree Cleanup on Success (Path A)
+
+The fix worktree is removed after a successful merge. This:
+
+- Frees disk space
+- Removes the now-merged branch reference
+- Keeps the list of active worktrees clean
+
+On failure, the worktree is preserved so you can:
+
+- Fix issues and retry `/hula-merge`
+- Manually clean up with: `git worktree remove "<path>" --force`
+- Or: `hula worktree cleanup`
+
+### Session File Lifecycle
+
+- Created by `/hula-fix`
+- Preserved if `/hula-merge` fails (so you can retry)
+- Deleted after successful merge OR cleaned up if stale (worktree missing)
+
+## Session File Format
+
+`.hublaunch/.fix-sessions/issue-42.json`:
+
+```json
+{
+  "issueNumber": 42,
+  "worktreePath": "<worktreePath>",
+  "prBranch": "fix/issue-42-button-color",
+  "localName": "fix button color",
+  "startedAt": "2025-12-22T14:30:00.000Z"
+}
+```
+
+## Success Criteria
+
+- ✅ Automatically detects local session vs remote-only merge path
+- ✅ Path A: Changes committed and pushed from within the fix worktree
+- ✅ Path A: Tests run if user requests (and changes exist)
+- ✅ Path A: Fix worktree removed after successful merge
+- ✅ Path A: Session file cleaned up
+- ✅ Path A: Local branch deleted after worktree removal
+- ✅ Path B: PR merged directly on GitHub without any local branch/worktree operations
+- ✅ Path B: Stale session files cleaned up if present
+- ✅ Path B: Local branch deleted if it existed locally
+- ✅ PR merged successfully (both paths)
+- ✅ Issue closed automatically (both paths)
+- ✅ Main working tree never modified (both paths)
+- ✅ Graceful error handling for conflicts, CI failures, pending reviews

package/dist/templates/skills/hula-plan/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: hula-plan
+description: Generate a detailed implementation plan for a GitHub issue. Use when the user asks to plan a feature, create a plan, or implement an issue.
+disable-model-invocation: true
+argument-hint: <feature or issue description> [--folder <subfolder>]
+allowed-tools: Bash Read
+---
+
+You are an expert technical planner for the HubLaunch project.
+
+## Instructions
+
+Read the detailed planning guidelines from the workspace file:
+
+`.hublaunch/planning-instructions.md`
+
+Follow those instructions carefully to generate a comprehensive implementation plan.
+
+## Context
+
+The user will describe a feature or issue. Your job is to:
+
+1. **ASK CLARIFYING QUESTIONS FIRST** - Do not immediately generate a plan
+2. Understand the requirements through questions and answers
+3. Analyze the existing codebase context
+4. Generate a structured plan following the template in planning-instructions.md
+5. Include specific file paths, code suggestions, and actionable steps
+6. Consider testing, documentation, and edge cases
+
+## Input
+
+Issue description: $ARGUMENTS
+Folder (optional): Parsed from $ARGUMENTS if --folder flag is provided
+
+## Additional Context
+
+Use the `#codebase` tool to search for relevant existing code:
+
+- Similar features to reference
+- Services that might be affected
+- Patterns to follow
+
+Use the `#file` tool to read specific files if needed to understand:
+
+- Current implementation details
+- Type definitions
+- Configuration structure
+
+## Deep Analysis Requirements
+
+**Before asking any clarifying questions**, you MUST perform an exhaustive codebase analysis:
+
+1. **Search exhaustively** — use workspace search, semantic search, and file reads to find ALL related code (not just the first match). Check all services, utilities, types, configurations, and templates that could be affected.
+2. **Trace dependencies end-to-end** — follow imports and understand how services connect to each other. Read every file that is transitively involved.
+3. **Read type definitions** — inspect interfaces, enums, and type aliases to understand data shapes.
+4. **Check existing patterns** — find similar features already implemented and follow the same patterns.
+5. **Review configuration** — check `.hublaunch/hublaunch.config.js` and any relevant config files for constraints.
+
+**Self-answer from code**: If you can determine the answer by reading source files, present it as a **finding**, NOT as a question. Format these as:
+
+> 📖 **Finding**: `GitService.deleteBranch()` already exists at `src/services/git/GitService.ts:58` and accepts a `force` flag.
+
+**Only ask what requires human judgment**: Business decisions, user preferences, ambiguous requirements, or trade-offs that genuinely cannot be resolved from code. Do not ask questions whose answers are already in the codebase.
+
+**Keep asking until 100% clear**: After the user answers your questions, if ANY ambiguity remains, ask follow-up questions in additional rounds. Do NOT proceed to planning with any uncertainty. Multiple rounds of clarification (2–3 rounds is normal and preferred) are expected over guessing or making assumptions.
+
+### Codebase Analysis Output Format
+
+Present your findings before asking questions:
+
+```
+## Codebase Analysis
+
+### Related Files Found
+- `src/...` — [what it does and why it's relevant]
+
+### Existing Patterns
+- [pattern name]: [where it's used and how]
+
+### Self-Answered Questions
+- ❓ Does X already exist? → ✅ Yes, at `src/...` (line N)
+- ❓ What type does Y use? → ✅ `TypeName` defined in `src/types/...`
+
+### Questions Requiring Human Judgment
+[Only genuinely ambiguous items go here]
+```
+
+## Output Requirements
+
+Generate a complete markdown document that includes:
+
+1. **Title**: Clear H1 heading suitable for a GitHub issue
+2. **Problem Statement**: Context and motivation
+3. **Proposed Solution**: High-level approach
+4. **Implementation Steps**: Detailed, actionable tasks organized in phases
+5. **Technical Considerations**: Dependencies, config, security, etc.
+6. **Testing Strategy**: Unit, integration, and manual tests
+7. **Documentation Updates**: What docs need updating
+8. **Acceptance Criteria**: Clear completion conditions
+
+The plan should be immediately actionable by a developer familiar with the codebase.
+
+## IMPORTANT: File Creation & Next Steps
+
+**You MUST create and save the plan file directly.** Do not just provide the content - actually create the file.
+
+### Step 1: Create the Plan File
+
+1. Read the planPath from `.hublaunch/hublaunch.config.js` (defaults to `.hublaunch/plans`)
+2. If a **folder** was provided, append it to the planPath (e.g. `.hublaunch/plans/auth` or `.hublaunch/plans/refactoring/v2`). Nested folders are supported.
+3. Generate the filename using the format: `YYYY-MM-DD-HH:MM-{brief-title-slug}.md`
+   - Use today's date and current time (24-hour format)
+   - Create a brief, lowercase, hyphenated slug from the title
+4. Save the plan file locally in the plans directory:
+   - Without folder: `.hublaunch/plans/<filename>.md`
+   - With folder: `.hublaunch/plans/<folder>/<filename>.md`
+   - Example: `.hublaunch/plans/auth/2025-12-29-14:30-feature-name.md`
+5. Create the full directory path (including any nested subfolders) if it doesn't exist
+6. Write the complete plan content to the file
+
+**⚠️ NEVER create plan files in the project root directory.** The plan file MUST always be inside the `.hublaunch/plans/` directory (or a subfolder of it). If you cannot read the config file, use the default path `.hublaunch/plans/`.
+
+### Step 2: Output the Plan Path and Next Steps
+
+**Output Format:**
+
+```
+✅ Plan created: `.hublaunch/plans/2025-12-29-14:30-feature-name.md`
+<!-- hula-plan: .hublaunch/plans/2025-12-29-14:30-feature-name.md -->
+
+📋 **Proceeding to validation now…**
+```
+
+Now proceed directly to plan validation **without waiting for the user**. The plan file was just created in this session — the path is already known.
+
+Read `.hublaunch/proceed-instructions.md` and execute the full validation workflow against the plan at `<path>` (substitute `<path>` with the actual plan file path you just created, e.g. `.hublaunch/plans/2025-12-29-14:30-feature-name.md`).
+
+**Important adjustments for inline execution:**
+
+- **Skip Step 1 (file location)** — the plan path is `<path>`. Do not ask "Is this correct?"
+- **Execute Step 2 onwards** — Comprehensive Validation Analysis, auto-fix, MCQ questions if needed, plan update, iterate until quality bar is met.
+- **Carry forward all context** from this planning session — you have full knowledge of the decisions made, which may help resolve validation questions.
+- **Recovery fallback** — If validation cannot complete (e.g. context limit, tool error), print:
+  > ⚠️ Auto-validation could not complete. Run `/hula-confirm <path>` to resume.
+
+  where `<path>` is the plan file path.
+
+**Note:** The plan is created locally and will need to be uploaded to origin/main before launching. The `/hula-upload` command will handle this seamlessly (stash, switch, commit, push, restore). `/hula-confirm` remains available as a standalone command for re-validation at any time.

package/dist/templates/skills/hula-upload/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: hula-upload
+description: Upload the current plan to origin/main via a temporary worktree. Use when the user asks to upload or sync the plan.
+disable-model-invocation: true
+argument-hint: "[plan-file-path]"
+allowed-tools: Bash Read
+---
+
+You are an expert HubLaunch workflow assistant, responsible for uploading implementation plans to the remote repository using an isolated worktree.
+
+## Instructions
+
+Your job is to:
+
+1. **Find the plan file path** from Copilot's own previous output in THIS chat:
+   - Look for the output from `/hula-plan` command
+   - Parse the plan file path from the message
+   - Also check for the HTML comment: `<!-- hula-plan: <path> -->`
+   - **CRITICAL**: Do NOT search the filesystem for plans — ONLY use the path from chat history
+
+2. **Error if no plan found**:
+   - If no plan path is found in the current chat history, show error:
+   - "❌ No plan found in this chat. Run `/hula-plan` first."
+   - Stop execution
+
+3. **Inform the user — upload is automatic**:
+   - Plan upload is handled automatically by `hula launch` — no separate upload command is needed.
+   - Display this message:
+     ```
+     ℹ️ Upload is no longer a separate step.
+
+     `hula launch` automatically uploads the plan to `origin/main` before starting the job.
+
+     **Next Step:** Run `/hula-launch <branch-name>` to upload and launch in one step.
+
+     <!-- hula-uploaded: <plan-path> -->
+     ```
+   - Do not run any shell command. Do not attempt to call `hula upload` or any upload CLI.
+
+4. **Done** — no further action needed.
+
+## Input Format
+
+```
+/hula-upload
+```
+
+No arguments needed — the plan path is extracted from chat history.
+
+User input: $ARGUMENTS
+
+## Workflow
+
+### Step 1: Find Plan in Chat History
+
+**CRITICAL**: Do NOT search the filesystem. ONLY look in the current chat history.
+
+Look for messages from `/hula-plan` command that contain:
+- Text like: "Plan created: `.hublaunch/plans/2025-12-22-14:30-feature-name.md`"
+- HTML comment: `<!-- hula-plan: .hublaunch/plans/2025-12-22-14:30-feature-name.md -->`
+
+If NOT found in chat history:
+```
+❌ No plan found in this chat. Run `/hula-plan` first.
+```
+
+Stop execution here.
+
+### Step 2: Validate Plan File
+
+Use the `#file` tool to verify the plan file exists.
+
+If not found:
+```
+❌ Plan file not found at <path>. The file may have been moved or deleted.
+```
+
+### Step 3: Inform User — Upload Is Automatic
+
+Plan upload is now handled automatically by `hula launch`. There is no separate upload CLI command.
+
+Display this message to the user:
+
+```
+ℹ️ Upload is no longer a separate step.
+
+`hula launch` automatically uploads the plan to `origin/main` before starting the job.
+
+**Next Step:** Run `/hula-launch <branch-name>` to upload and launch in one step.
+
+<!-- hula-uploaded: <plan-path> -->
+```
+
+Do not run any shell command. Do not attempt to call `hula upload` or any upload CLI.
+
+### Step 4: Done
+
+No further action needed. The message from Step 3 is the final output.
+
+## Important Notes
+
+- This command uploads the plan from your local branch to `origin/main` using an isolated worktree
+- The plan file in your main working tree is **never modified by upload** — it remains untouched. (It will be automatically removed later when `/hula-launch` or `/hula-create` succeeds, since it's already on origin/main.)
+- The plan must be uploaded before running `/hula-launch`
+- If the plan is already on `origin/main`, the command will confirm this
+- This is typically run after `/hula-plan` and `/hula-confirm`, before `/hula-launch`
+
+## Typical Workflow
+
+```
+/hula-plan Add user authentication    # Create the plan
+/hula-confirm                          # Refine the plan
+/hula-upload                           # Sync plan to origin/main (worktree-based, non-destructive)
+/hula-launch feature-auth              # Launch the issue
+```