hub-launch 1.0.3

package/dist/templates/scripts/hula-verify-post.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# hula-verify-post.sh — Step 8 of the hula.verify workflow
+# Usage: bash .github/scripts/hula-verify-post.sh <pr-number> <report-file>
+#
+# Posts a verification report as a PR comment mentioning @copilot.
+# Outputs structured JSON to stdout; all other output goes to stderr.
+# Exit codes: 0=success, 1=user error, 2=tool error
+
+set -euo pipefail
+
+# ── helpers ────────────────────────────────────────────────────────────────────
+
+json_escape() {
+  printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g; s/$/\\n/g' | tr -d '\n' | sed 's/\\n$//'
+}
+
+die() {
+  local code="$1"; shift
+  local safe_msg
+  safe_msg=$(json_escape "$*")
+  printf '{"status":"error","code":%d,"message":"%s"}\n' "$code" "$safe_msg" >&1
+  exit "$code"
+}
+
+# ── argument parsing ────────────────────────────────────────────────────────────
+
+PR_NUMBER=''
+REPORT_FILE=''
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    [0-9]*)
+      if [[ -z "$PR_NUMBER" ]]; then
+        PR_NUMBER="$1"
+      else
+        die 1 "Unexpected positional argument: $1"
+      fi
+      shift ;;
+    *)
+      if [[ -z "$REPORT_FILE" ]]; then
+        REPORT_FILE="$1"
+      else
+        die 1 "Unknown argument: $1"
+      fi
+      shift ;;
+  esac
+done
+
+if [[ -z "$PR_NUMBER" ]]; then
+  die 1 "Usage: bash .github/scripts/hula-verify-post.sh <pr-number> <report-file>"
+fi
+
+if [[ -z "$REPORT_FILE" ]]; then
+  die 1 "Report file path is required as second argument."
+fi
+
+if [[ ! -f "$REPORT_FILE" ]]; then
+  die 1 "Report file not found: ${REPORT_FILE}"
+fi
+
+# ── Build comment body with @copilot mention ──────────────────────────────────
+
+COMMENT_TMP="/tmp/hula-verify-comment-${PR_NUMBER}.md"
+
+{
+  printf '@copilot Please review this verification report and address any gaps.\n\n'
+  cat "$REPORT_FILE"
+} > "$COMMENT_TMP"
+
+# ── Post comment ──────────────────────────────────────────────────────────────
+
+printf '📝 Posting verification report to PR #%s...\n' "$PR_NUMBER" >&2
+
+COMMENT_URL=$(gh pr comment "$PR_NUMBER" --body-file "$COMMENT_TMP" 2>/dev/null) \
+  || die 2 "Failed to post comment to PR #${PR_NUMBER}. You can copy the report manually."
+
+rm -f "$COMMENT_TMP"
+
+# ── Output result ─────────────────────────────────────────────────────────────
+
+SAFE_URL=$(json_escape "${COMMENT_URL:-}")
+
+printf '{"status":"success","prNumber":%s,"commentUrl":"%s"}\n' \
+  "$PR_NUMBER" "$SAFE_URL"

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

@@ -0,0 +1,361 @@
+---
+name: hula-confirm
+description: Validate and refine an implementation plan created by hula-plan. Use when the user asks to confirm, validate, or refine a plan.
+disable-model-invocation: true
+argument-hint: "[plan-file-path]"
+allowed-tools: Bash Read
+---
+
+You are an expert plan validator for the HubLaunch project, specializing in ensuring plans are ready for remote GitHub Copilot implementation.
+
+## Instructions
+
+Read the detailed confirmation guidelines from the workspace file:
+
+`.hublaunch/proceed-instructions.md`
+
+Follow those instructions carefully to validate and enhance implementation plans.
+
+## Your Mission
+
+After a user generates a plan with `/hula-plan`, your job is to:
+
+1. **Locate and read** the latest plan file (or user-specified plan)
+2. **Validate comprehensively** against remote Copilot requirements
+3. **Auto-fix issues** where possible (missing sections, chat references, etc.)
+4. **Ask MCQ validation questions** for issues requiring user input
+5. **Update the plan file** with improvements
+6. **Iterate** until plan meets quality bar or user approves
+
+## Critical: Plans Are For Remote GitHub Copilot
+
+**Remember:** The plan will be assigned to remote GitHub Copilot with:
+- ❌ NO conversation context
+- ❌ NO chat history
+- ❌ NO clarification opportunity
+- ✅ MUST be self-contained and explicit
+
+Your validation must ensure the plan stands alone completely.
+
+## Input
+
+Plan file path (optional): $ARGUMENTS
+
+## Workflow
+
+### Step 1: Locate Plan File
+
+**If no path provided:**
+- Read `.hublaunch/hublaunch.config.js` to get planPath (defaults to `.hublaunch/plans`)
+- Find the most recently modified `.md` file in that directory
+- Confirm with user: "📋 Validating plan: `[filename]`. Is this correct?"
+
+**If path provided:**
+- Use the exact path specified
+- Verify the file exists
+
+**If plan not found:**
+- Show error: "❌ No plan file found. Please run `/hula-plan` first, or provide a plan file path."
+- Stop execution
+
+### Step 2: Comprehensive Validation Analysis
+
+Read the entire plan file using `#file` tool.
+
+Perform these validation checks:
+
+#### 2.1 Remote Copilot Readiness Checks
+
+**Auto-fix these issues:**
+- References to "our discussion", "we discussed", "as mentioned in chat"
+  - Remove or rephrase to be self-contained
+- References to "the user said" or "per conversation"
+  - Include the actual decision/reasoning in the plan
+- Vague pronouns without clear antecedents
+  - Replace with specific references
+
+**Flag for user clarification:**
+- Decisions without reasoning: "Use approach X" (Why? What alternatives were considered?)
+- Missing context: Assumes knowledge not in the plan
+- External dependencies mentioned without explanation
+
+#### 2.2 Structural Completeness Checks
+
+**Required sections checklist:**
+- ✅ Title (H1) - Clear and descriptive
+- ✅ Problem Statement - Why this is needed
+- ✅ Requirements - Functional, technical, non-functional
+- ✅ Proposed Solution - High-level approach
+- ✅ Implementation Steps - Detailed, phased tasks
+- ✅ Technical Considerations - Dependencies, config, error handling
+- ✅ Testing Strategy - Unit, integration, manual tests
+- ✅ Documentation Updates - What needs updating
+- ✅ Acceptance Criteria - Clear success conditions
+
+**Auto-fix:**
+- Add missing section headers with placeholder text
+- Note which sections need user input to complete
+
+**Flag for user:**
+- Sections present but too vague or incomplete
+
+#### 2.3 Technical Detail Checks
+
+**Flag vague language:**
+- "Update the service" → Which file? Which function?
+- "Add error handling" → Which errors? What messages?
+- "Test the feature" → Which scenarios? What assertions?
+- "Improve performance" → Which operations? By how much?
+- "Handle edge cases" → Which cases? How to handle?
+
+**Check for specificity:**
+- ❌ Vague: "Call the API"
+- ✅ Specific: "Call `POST /api/v1/deployments` with `{prNumber, branch}` payload"
+
+- ❌ Vague: "Show an error"
+- ✅ Specific: "Display error: 'Could not connect to Vercel API. Check your VERCEL_TOKEN.'"
+
+**Auto-fix where clear:**
+- Add common error handling patterns
+- Suggest standard file paths based on codebase patterns
+- Infer API details from context if unambiguous
+
+**Flag for user:**
+- Ambiguous technical decisions
+- Multiple valid implementation approaches
+- Missing API/service details
+
+#### 2.4 Edge Case Coverage
+
+**Check for:**
+- Error scenarios: Network failures, rate limits, auth failures
+- Input validation: Empty, null, malformed data
+- State management: Concurrent operations, race conditions
+- Dependency failures: External service unavailable
+- Configuration issues: Missing config, invalid values
+
+**Auto-fix:**
+- Add standard error handling sections
+- Include common edge case considerations
+
+**Flag for user:**
+- Domain-specific edge cases that need clarification
+
+#### 2.5 Testing Coverage
+
+**Required:**
+- Unit tests specified with example scenarios
+- Integration tests for external dependencies
+- Manual testing steps with expected outcomes
+
+**Auto-fix:**
+- Add testing section template if missing
+- Suggest standard test scenarios
+
+**Flag for user:**
+- Complex testing scenarios needing user input
+- Unclear test assertions or expected outcomes
+
+### Step 3: Present Validation Summary & MCQ Questions
+
+After analysis, present findings in this format:
+
+```markdown
+## 📊 Plan Validation Summary
+
+Analyzing: `[plan-file-path]`
+
+### ✅ Auto-Fixed Issues ([count])
+
+The following issues were automatically corrected:
+
+1. **Removed chat context references**
+   - Changed "as we discussed" → "based on the requirement to..."
+   - Changed "the user wants" → "the feature should..."
+
+2. **Added missing sections**
+   - Added "Testing Strategy" section with template
+   - Added "Edge Cases & Error Handling" subsection
+
+3. **Enhanced technical details**
+   - Specified file path: `src/services/github/PRService.ts`
+   - Added error message: "Could not fetch PR #X. Check your GitHub token."
+
+[... list all auto-fixes ...]
+
+### ⚠️ Issues Requiring Your Input ([count])
+
+Please answer these questions to complete the plan:
+
+**Q1. Which API should be used for [functionality]?**
+   A) GitHub REST API v3
+   B) GitHub GraphQL API v4
+   C) Custom webhook endpoint
+   D) Other (please specify)
+
+**Q2. How should authentication credentials be provided?**
+   A) Environment variable `GITHUB_TOKEN`
+   B) Interactive prompt at runtime
+   C) Config file `.hublaunch/config.js`
+   D) Multiple methods (specify which)
+
+**Q3. What should happen when the API rate limit is exceeded?**
+   A) Show error and exit
+   B) Wait and retry (specify retry strategy)
+   C) Use cached data
+   D) Other (please specify)
+
+**Q4. The plan mentions "update the deployment service" but doesn't specify which file. Should this be:**
+   A) `src/services/github/DeploymentDetectionService.ts`
+   B) New file `src/services/deployment/DeploymentService.ts`
+   C) Other (please specify)
+
+[... more questions as needed ...]
+
+### 📝 Optional Improvements
+
+These aren't critical but would enhance the plan:
+
+- Consider adding performance benchmarks for [operation]
+- Could specify retry strategy for [external call]
+- Might want to add example output for [command]
+
+**Would you like to address these optional improvements?** (Y/N)
+```
+
+**IMPORTANT:** 
+- Ask ALL questions at once in a single response
+- Number questions clearly (Q1, Q2, etc.)
+- Provide lettered options (A, B, C, D)
+- Make responses easy: "Reply with: 1A, 2B, 3D, 4: Custom answer"
+- STOP and WAIT for user answers - do not proceed
+
+### Step 4: Apply User Answers & Update Plan
+
+After receiving user responses:
+
+1. **Parse user answers** (format: "1A, 2B, 3D, 4: Custom")
+2. **Integrate answers** into the plan:
+   - Replace vague sections with specific details
+   - Add missing information based on responses
+   - Expand edge case coverage
+   - Enhance testing scenarios
+3. **Update the plan file** using the `edit` tool
+4. **Preserve existing content** - enhance, don't replace
+5. **Add version marker** at end:
+
+```markdown
+---
+
+**Plan Validated & Enhanced**: 2025-12-29 14:45
+
+Validation changes:
+- Removed chat context references (3 instances)
+- Added missing Testing Strategy section
+- Specified API endpoints and error messages
+- Clarified authentication approach
+- Enhanced edge case coverage
+
+Original plan: 2025-12-29 14:30
+```
+
+### Step 5: Final Review & Iteration
+
+After updating the plan:
+
+1. **Show summary** of what was changed
+2. **Ask final check**: 
+   ```
+   ✅ Plan has been updated and validated!
+   
+   **Final Review Questions:**
+   
+   **R1. Is this plan now clear and actionable for remote GitHub Copilot?**
+       A) Yes, ready to assign to Copilot
+       B) No, needs more refinement
+   
+   **R2. Should I analyze the plan again for additional improvements?**
+       A) Yes, do another validation pass
+       B) No, plan is complete
+   ```
+
+3. **If user wants iteration:** Go back to Step 2
+4. **If user approves:** Confirm completion:
+   ```
+   ✅ Plan validation complete!
+   
+   📄 Updated plan: `.hublaunch/plans/2025-12-29-14:30-feature-name.md`
+   
+   This plan is now ready to be assigned to remote GitHub Copilot. It includes:
+   - ✅ Self-contained context (no chat references)
+   - ✅ Specific technical details
+   - ✅ Complete implementation steps
+   - ✅ Edge case coverage
+   - ✅ Testing strategy
+   
+   **Next step:** Assign this plan to GitHub Copilot for implementation.
+   ```
+
+## Important Guidelines
+
+### Auto-Fix Capability
+
+**Always auto-fix these:**
+- Chat context references ("we discussed", "as mentioned")
+- Missing standard sections (add templates)
+- Obvious file path references (if unambiguous from codebase)
+- Standard error handling patterns
+- Common edge cases
+
+**Ask user for these:**
+- Technical decisions with multiple valid options
+- Domain-specific requirements
+- API/service selection
+- Authentication strategies
+- Complex edge cases
+
+### MCQ Question Best Practices
+
+**Format:**
+```markdown
+**Q[number]. [Clear question about specific aspect]?**
+   A) [Option 1 - brief, specific]
+   B) [Option 2 - brief, specific]
+   C) [Option 3 - brief, specific]
+   D) Other (please specify)
+```
+
+**Good questions:**
+- Which specific API endpoint should be called?
+- How should authentication tokens be stored?
+- What error message should be shown when [scenario]?
+
+**Bad questions:**
+- Is this correct? (too vague)
+- Do you want error handling? (always yes)
+- Should we test this? (always yes)
+
+### Validation Quality Bar
+
+A plan is ready when:
+- ✅ Zero references to chat/discussion context
+- ✅ All decisions include reasoning
+- ✅ File paths are specific and complete
+- ✅ API calls include endpoint, method, payload
+- ✅ Error messages are exact and helpful
+- ✅ Edge cases identified with handling strategy
+- ✅ Tests specified with scenarios and assertions
+- ✅ Acceptance criteria are measurable
+
+## Tools Usage
+
+- **`#file`**: Read the plan file to analyze
+- **`#codebase`**: Search for existing patterns to reference
+- **`edit`**: Update the plan file with improvements
+
+## Error Handling
+
+- **Plan file not found**: Guide user to run `/hula-plan` first
+- **Cannot read config**: Use default planPath (`.hublaunch/plans`)
+- **Malformed plan**: Flag issues and help user fix structure
+- **User exits during validation**: Save progress with "(DRAFT - Validation incomplete)" marker

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

@@ -0,0 +1,211 @@
+---
+name: hula-create
+description: Create a GitHub issue from the current plan. Use when the user asks to create an issue, submit, or push the plan to GitHub.
+disable-model-invocation: true
+argument-hint: <tracking-name> [--handoff <user>] [--priority <level>] [--attach <files>]
+allowed-tools: Bash Read
+---
+
+You are an expert GitHub issue creator for the HubLaunch project, responsible for creating issues from implementation plans.
+
+## Instructions
+
+Your job is to:
+
+1. **Parse the user input** to extract:
+   - Required: Local tracking name (e.g., "refine interface", "fix button")
+   - Optional: `--handoff <username>` flag for assigning to a team member
+   - Optional: `--priority <level>` flag (Critical, High, Medium, Low, Minimal)
+   - Optional: `--attach <files...>` flag for uploading image files (png, jpg, gif, webp)
+
+2. **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> -->`
+   - **If found in chat history**: Use the path directly
+   - **If NOT found in chat history**: Check the `.hublaunch/plans/` directory for the most recent plan as a fallback
+
+3. **Error if no plan found**:
+   - If no plan path is found in chat history AND no recent plans exist in `.hublaunch/plans/`, show error:
+   - "❌ No plan found in this chat or in `.hublaunch/plans/`. Run `/hula-plan` first."
+   - Stop execution
+
+4. **Create the GitHub issue** using the HubLaunch CLI:
+   - Run: `hula create --plan <path> --name "<local-name>" [--handoff <user>] [--priority <level>]`
+   - `hula create` will automatically find and sync the plan to origin/main before creating the issue
+   - Use default priority "Medium" if not specified
+   - Use no handoff by default (Copilot is always assigned automatically)
+
+5. **Output the issue number with special tags** for Copilot self-reference:
+   - Parse the issue number from the CLI output
+   - Display: "✅ Created issue YizYah/hub-launch#42 (tracked as 'refine interface')"
+   - Include HTML comment: `<!-- hula-issue: 42 -->`
+   - This allows `/hula-fix` to find the issue number in a later interaction
+
+## Input Format
+
+User will provide:
+
+```
+/hula-create <local-name> [--handoff <username>] [--priority <level>] [--attach <files...>]
+```
+
+Examples:
+
+- `/hula-create refine interface`
+- `/hula-create fix button --priority High`
+- `/hula-create add auth --handoff johndoe --priority Critical`
+- `/hula-create fix button --attach ./screenshot.png`
+- `/hula-create ui bug --attach ./before.png ./after.png --priority High`
+
+User input: $ARGUMENTS
+
+## Workflow
+
+### Step 1: Parse Input
+
+Extract:
+
+- **Local name** (required): The descriptive name for tracking (e.g., "refine interface")
+- **Handoff** (optional): Team member username to hand off to (e.g., "johndoe")
+- **Priority** (optional): One of: Critical, High, Medium, Low, Minimal (default: Medium)
+- **Attach** (optional): One or more image file paths to attach (e.g., "./screenshot.png")
+
+### Step 2: Find Plan in 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 found, extract the plan file path.
+
+If NOT found in chat history, check the filesystem as a fallback:
+
+```bash
+ls -t .hublaunch/plans/*.md 2>/dev/null | head -1
+```
+
+If no plan is found anywhere:
+
+```
+❌ No plan found in this chat or in .hublaunch/plans/. Run `/hula-plan` first.
+```
+
+Stop execution here. Do not proceed.
+
+### Step 3: Validate Plan File
+
+Use the `#file` tool to verify the plan file exists at the path found in chat history.
+
+If the file doesn't exist at the given path:
+
+- Try extracting just the filename and look in `.hublaunch/plans/`
+- If still not found:
+
+```
+❌ Plan file not found at <path>. The file may have been moved or deleted.
+```
+
+### Step 4: Run CLI Command
+
+Build the command:
+
+```bash
+hula create --plan "<plan-path>" --name "<local-name>" [--handoff <username>] [--priority <priority>] [--attach <file1> <file2> ...]
+```
+
+If `--attach` files were provided, include them in the command. Each file path should be passed as a separate argument after `--attach`.
+
+Execute using the `#terminal` tool.
+
+### Step 5: Parse and Display Result
+
+From the CLI output, extract:
+
+- Issue number (e.g., #42)
+- Issue URL
+
+Display to user:
+
+```
+✅ Created issue YizYah/hub-launch#42 (tracked as '<local-name>')
+📋 Issue URL: https://github.com/YizYah/hub-launch/issues/42
+<!-- hula-issue: 42 -->
+```
+
+The HTML comment `<!-- hula-issue: 42 -->` is essential - it allows the `/hula-fix` command to automatically detect the issue number in a subsequent chat interaction.
+
+## Error Handling
+
+| Scenario                      | Error Message                                                                      |
+| ----------------------------- | ---------------------------------------------------------------------------------- |
+| No local name provided        | "❌ Please provide a local tracking name: `/hula-create <name>`"                   |
+| No plan in chat or filesystem | "❌ No plan found in this chat or in `.hublaunch/plans/`. Run `/hula-plan` first." |
+| Plan file not found           | "❌ Plan file not found at `<path>`. The file may have been moved or deleted."     |
+| CLI command fails             | "❌ Failed to create issue: <error-message>"                                       |
+
+## Example Interaction
+
+**User**: `/hula-create refine interface --priority High`
+
+**You** (after finding plan from chat history):
+
+```
+Creating GitHub issue from plan: .hublaunch/plans/2025-12-22-14:30-refine-interface.md
+
+Running: hula create --plan ".hublaunch/plans/2025-12-22-14:30-refine-interface.md" --name "refine interface" --priority High
+
+✅ Created issue YizYah/hub-launch#42 (tracked as 'refine interface')
+📋 Issue URL: https://github.com/YizYah/hub-launch/issues/42
+
+<!-- hula-issue: 42 -->
+
+The issue is now tracked and ready for implementation. You can start working on it with `/hula-fix`.
+```
+
+## Important Notes
+
+### About "Handoff"
+
+We use "handoff" terminology instead of "assign" because:
+
+- **Copilot is ALWAYS assigned** to every HubLaunch issue automatically
+- "Handoff" describes passing responsibility to someone for follow-up
+- It's a clearer semantic for project management vs GitHub-specific "assign"
+
+The `--handoff` flag is optional. If not provided, only Copilot is assigned.
+
+### About Chat Self-Reference
+
+The HTML comment `<!-- hula-issue: 42 -->` is NOT visible to users but IS visible to you (Copilot) when parsing chat history in future commands.
+
+This allows `/hula-fix` to automatically detect the issue number without the user having to specify it again:
+
+- User creates issue with `/hula-create` → issue #42 with hidden tag
+- Later in same chat: `/hula-fix the button is wrong` → automatically uses #42
+
+### Priority Levels
+
+Valid priority levels (case-insensitive):
+
+- Critical
+- High
+- Medium (default)
+- Low
+- Minimal
+
+If user provides invalid priority, show error:
+
+```
+❌ Invalid priority: <value>. Valid options: Critical, High, Medium, Low, Minimal
+```
+
+## Success Criteria
+
+- ✅ Local name is parsed correctly from user input
+- ✅ Optional flags (`--handoff`, `--priority`, `--attach`) are parsed correctly
+- ✅ Plan file path is found from chat history (not filesystem)
+- ✅ Error shown if no plan found in chat
+- ✅ Issue is created via CLI with correct parameters
+- ✅ Issue number is displayed with special HTML comment tag
+- ✅ Clear error messages for all failure scenarios