@forloop-cc/forloop-opencode-plugin-planner 2.2.1

package/docs/superpowers/plans/2026-05-29-install-system.md

@@ -0,0 +1,850 @@
+# Install System 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:** Build curl-pipeable `install.sh` and `update.sh` scripts with npm+git support, local+global install, and jq-based config merging that preserves existing opencode configuration.
+
+**Architecture:** Two standalone bash scripts at repo root. `install.sh` handles first-time setup (git clone or npm install, dep checks, config merge, token setup). `update.sh` handles upgrades (auto-detect install, git pull or npm update). Both are curl-pipeable from GitHub raw URLs. `package.json` updated with `files` field for npm publishing.
+
+**Tech Stack:** Bash 3.2+ (macOS/Linux/Windows Git Bash), jq, git, npm, curl
+
+---
+
+## File Structure
+
+| File | Action | Responsibility |
+|------|--------|---------------|
+| `install.sh` | Rewrite | One-liner installer — dep checks, git clone/npm install, config merge, token setup |
+| `update.sh` | Rewrite | Auto-detect install location, git pull or npm update, show changelog |
+| `package.json` | Modify | Add `files` field for npm publishing |
+
+---
+
+### Task 1: Rewrite `install.sh`
+
+**Files:**
+- Rewrite: `forloop-opencode-plugin-planner/install.sh`
+- Read reference: `forloop-opencode-plugin-planner/plugins/forloop-plugin.ts` (to verify entry point path)
+
+- [ ] **Step 1: Write the install.sh script**
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ForLoop Plugin Installer
+# https://github.com/forloop-cc/forloop-opencode-plugin-planner
+#
+# Usage:
+#   curl -fsSL https://raw.githubusercontent.com/forloop-cc/forloop-opencode-plugin-planner/main/install.sh | bash
+#   curl -fsSL ... | bash -s -- --global
+#   bash install.sh --local --force
+#   bash install.sh --npm --global
+
+# ── Platform & colors ────────────────────────────────────────────────────────
+PLATFORM="$(uname -s)"
+case "$PLATFORM" in
+    Darwin*)    PLATFORM_LABEL="macOS";;
+    Linux*)     PLATFORM_LABEL="Linux";;
+    CYGWIN*|MINGW*|MSYS*) PLATFORM_LABEL="Windows";;
+    *)          PLATFORM_LABEL="Unknown";;
+esac
+
+if [ "$PLATFORM_LABEL" = "Windows" ] && [ -z "$WT_SESSION" ] && [ -z "$ConEmuPID" ]; then
+    RED=''; GREEN=''; YELLOW=''; BLUE=''; CYAN=''; BOLD=''; NC=''
+else
+    RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'
+    BLUE='\033[0;34m'; CYAN='\033[0;36m'; BOLD='\033[1m'; NC='\033[0m'
+fi
+
+# ── Configuration ────────────────────────────────────────────────────────────
+REPO="https://github.com/forloop-cc/forloop-opencode-plugin-planner.git"
+RAW_URL="https://raw.githubusercontent.com/forloop-cc/forloop-opencode-plugin-planner/main"
+BRANCH="${FORLOOP_BRANCH:-main}"
+PLUGIN_DIRNAME="forloop-planner"
+GLOBAL_INSTALL_DIR="$HOME/.config/opencode/plugins/$PLUGIN_DIRNAME"
+LOCAL_INSTALL_DIR=".opencode/plugins/$PLUGIN_DIRNAME"
+ENTRY_POINT="plugins/forloop-plugin.ts"
+
+INSTALL_TYPE=""      # global | local | custom
+INSTALL_DIR=""       # resolved path
+USE_NPM=false
+FORCE=false
+NON_INTERACTIVE=false
+
+print_header() { echo -e "${BLUE}${BOLD}╔══════════════════════════════════════════╗\n║       ForLoop Plugin Installer           ║\n╚══════════════════════════════════════════╝${NC}\n"; }
+print_success() { echo -e "${GREEN}✓${NC} $1"; }
+print_info()    { echo -e "${BLUE}ℹ${NC} $1"; }
+print_warning() { echo -e "${YELLOW}⚠${NC} $1"; }
+print_error()   { echo -e "${RED}✗${NC} $1" >&2; }
+print_step()    { echo -e "\n${CYAN}${BOLD}▶${NC} $1\n"; }
+
+show_help() {
+    cat << EOF
+Usage: install.sh [OPTIONS]
+
+Options:
+  -g, --global     Install globally (~/.config/opencode/plugins/)
+  -l, --local      Install locally (./.opencode/plugins/)
+  -d, --dir PATH   Custom install directory
+  -n, --npm        Use npm install instead of git clone
+  -b, --branch NAME  Clone a specific branch (default: $BRANCH)
+  -f, --force      Overwrite existing installation
+  -h, --help       Show this help
+
+Examples:
+  curl -fsSL .../install.sh | bash              # Interactive
+  curl -fsSL .../install.sh | bash -s -- -g     # Global, non-interactive
+  bash install.sh --local --force               # Local, force overwrite
+  bash install.sh --npm --global                # npm install, global
+EOF
+}
+
+# ── Dependency checks ────────────────────────────────────────────────────────
+
+check_git() {
+    if ! command -v git &>/dev/null; then
+        print_error "git is required but not installed"
+        case "$PLATFORM_LABEL" in
+            macOS)   echo "  brew install git" ;;
+            Linux)   echo "  sudo apt-get install git  (Ubuntu/Debian)"
+                     echo "  sudo dnf install git      (Fedora/RHEL)" ;;
+            Windows) echo "  https://git-scm.com/download/win" ;;
+        esac
+        return 1
+    fi
+    return 0
+}
+
+check_node() {
+    if ! command -v node &>/dev/null; then
+        print_warning "Node.js not found (needed for npm install)"
+        case "$PLATFORM_LABEL" in
+            macOS)   echo "  brew install node" ;;
+            Linux)   echo "  curl -fsSL https://deb.nodesource.com/setup_20.x | bash -"
+                     echo "  sudo apt-get install -y nodejs" ;;
+            Windows) echo "  https://nodejs.org" ;;
+        esac
+        if [ "$NON_INTERACTIVE" = true ]; then
+            print_info "Continuing anyway (npm install will be attempted)..."
+        else
+            read -p "Continue anyway? [y/N] " -r; echo
+            [[ ! $REPLY =~ ^[Yy]$ ]] && return 1
+        fi
+    fi
+    return 0
+}
+
+check_jq() {
+    if ! command -v jq &>/dev/null; then
+        print_error "jq is required for config merging"
+        case "$PLATFORM_LABEL" in
+            macOS)   echo "  brew install jq" ;;
+            Linux)   echo "  sudo apt-get install jq  (Ubuntu/Debian)"
+                     echo "  sudo dnf install jq      (Fedora/RHEL)" ;;
+            Windows) echo "  scoop install jq  or https://stedolan.github.io/jq/download/" ;;
+        esac
+        return 1
+    fi
+    return 0
+}
+
+check_opencode() {
+    if command -v opencode &>/dev/null; then
+        print_success "OpenCode CLI found: $(which opencode)"
+    else
+        print_warning "OpenCode CLI not found"
+        echo "  Install: curl -fsSL https://opencode.ai/install.sh | bash"
+        if [ "$NON_INTERACTIVE" != true ]; then
+            read -p "Continue anyway? [y/N] " -r; echo
+            [[ ! $REPLY =~ ^[Yy]$ ]] && exit 1
+        fi
+    fi
+}
+
+check_all_deps() {
+    print_step "Checking dependencies..."
+    local missing=0
+    check_git || true  # always check git
+    [ "$USE_NPM" != true ] && { check_git || missing=$((missing + 1)); }
+    check_node || missing=$((missing + 1))
+    check_jq || missing=$((missing + 1))
+    if [ "$missing" -gt 0 ]; then
+        print_error "Missing $missing required dependencies. Install them and try again."
+        exit 1
+    fi
+    print_success "All dependencies found"
+}
+
+# ── Install location ─────────────────────────────────────────────────────────
+
+resolve_install_dir() {
+    case "$INSTALL_TYPE" in
+        global)  INSTALL_DIR="$GLOBAL_INSTALL_DIR" ;;
+        local)   INSTALL_DIR="$LOCAL_INSTALL_DIR" ;;
+        custom)  ;;  # INSTALL_DIR already set by --dir flag
+    esac
+
+    local parent_dir
+    parent_dir="$(dirname "$INSTALL_DIR")"
+    if [ ! -d "$parent_dir" ]; then
+        print_info "Creating parent directory: $parent_dir"
+        mkdir -p "$parent_dir"
+    fi
+}
+
+prompt_install_type() {
+    echo -e "${BOLD}Choose installation type:${NC}"
+    echo "  1) Global — available for all projects (~/.config/opencode/plugins/)"
+    echo "  2) Local — only for this project (./.opencode/plugins/)"
+    echo "  3) Cancel"
+    read -p "Select [1-3]: " -r; echo
+    case "$REPLY" in
+        1) INSTALL_TYPE="global" ;;
+        2) INSTALL_TYPE="local" ;;
+        *) print_info "Installation cancelled"; exit 0 ;;
+    esac
+}
+
+# ── Installation ─────────────────────────────────────────────────────────────
+
+install_via_git() {
+    print_step "Cloning plugin repository..."
+    local clone_dir="$INSTALL_DIR"
+
+    if [ -d "$clone_dir" ] && [ "$FORCE" = true ]; then
+        print_warning "Removing existing installation..."
+        rm -rf "$clone_dir"
+    elif [ -d "$clone_dir" ]; then
+        print_warning "Plugin already installed at: $clone_dir"
+        if [ "$NON_INTERACTIVE" = true ]; then
+            print_error "Use --force to overwrite in non-interactive mode"
+            exit 1
+        fi
+        read -p "Overwrite? [y/N] " -r; echo
+        if [[ $REPLY =~ ^[Yy]$ ]]; then
+            rm -rf "$clone_dir"
+        else
+            print_info "Installation cancelled"
+            exit 0
+        fi
+    fi
+
+    mkdir -p "$clone_dir"
+    git clone --depth 1 --branch "$BRANCH" "$REPO" "$clone_dir" --quiet
+
+    print_success "Repository cloned to: $clone_dir"
+
+    print_step "Installing dependencies..."
+    cd "$clone_dir"
+    npm install --omit=dev --silent
+    print_success "Dependencies installed"
+}
+
+install_via_npm() {
+    print_step "Installing via npm..."
+    local npm_package="@forloop/opencode-plugin-planner"
+
+    if npm install "$npm_package" --prefix "$INSTALL_DIR" --silent 2>/dev/null; then
+        print_success "npm package installed: $npm_package"
+    else
+        print_error "npm install failed. Is the package published?"
+        echo "  Try: npm install $npm_package    (manually)"
+        echo "  Or run without --npm to use git clone instead"
+        exit 1
+    fi
+}
+
+# ── Config merging ───────────────────────────────────────────────────────────
+
+get_config_file() {
+    if [ "$INSTALL_TYPE" = "global" ]; then
+        mkdir -p "$HOME/.config/opencode"
+        echo "$HOME/.config/opencode/config.json"
+    else
+        echo "$(pwd)/opencode.json"
+    fi
+}
+
+merge_plugin_into_config() {
+    local config_file
+    config_file="$(get_config_file)"
+    local plugin_path="file://$INSTALL_DIR"
+
+    print_step "Updating OpenCode configuration..."
+
+    if [ ! -f "$config_file" ]; then
+        echo "{}" > "$config_file"
+    fi
+
+    local backup="${config_file}.backup.$(date +%Y%m%d%H%M%S)"
+    cp "$config_file" "$backup"
+
+    local tmp
+    tmp="$(mktemp)"
+
+    jq --arg p "$plugin_path" '
+        if .plugin then
+            .plugin += [$p] | .plugin |= unique
+        else
+            . + {"plugin": [$p]}
+        end
+    ' "$config_file" > "$tmp"
+
+    if [ -s "$tmp" ]; then
+        mv "$tmp" "$config_file"
+        print_success "Configuration updated: $config_file"
+        print_info "Backup saved: $backup"
+    else
+        print_error "Config merge produced empty file — restoring backup"
+        mv "$backup" "$config_file"
+        rm -f "$tmp"
+        exit 1
+    fi
+}
+
+# ── Token setup ──────────────────────────────────────────────────────────────
+
+setup_token() {
+    echo ""
+    print_step "Setting up API token..."
+    echo "  Create a token at: https://forloop.cc/profile?tab=api-tokens"
+    echo "  Scopes needed: sprint:read, sprint:write, story:read, story:write, agent:query, profile:read"
+    echo ""
+
+    if [ "$NON_INTERACTIVE" = true ]; then
+        print_info "Non-interactive mode — set your token later:"
+        echo "  opencode run 'forloopTokenSet --token floop_YOUR_TOKEN'"
+        return
+    fi
+
+    read -p "Have you created a token? [y/N] " -r; echo
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        print_info "Set it later: opencode run 'forloopTokenSet --token floop_YOUR_TOKEN'"
+        return
+    fi
+
+    read -p "Enter your token: " -s TOKEN; echo
+    if [ -z "$TOKEN" ]; then
+        print_info "No token entered, skipping"
+        return
+    fi
+
+    local token_dir="$HOME/.config/forloop"
+    mkdir -p "$token_dir"
+    cat > "$token_dir/tokens.json" << TOKENEOF
+{
+  "version": "1.0",
+  "note": "ForLoop API tokens — do not share",
+  "default": "$TOKEN",
+  "lastUpdated": "$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")"
+}
+TOKENEOF
+    chmod 600 "$token_dir/tokens.json"
+    print_success "Token saved to: $token_dir/tokens.json"
+}
+
+# ── Verification ─────────────────────────────────────────────────────────────
+
+verify_installation() {
+    print_step "Verifying installation..."
+    local entry="$INSTALL_DIR/$ENTRY_POINT"
+
+    if [ -f "$entry" ]; then
+        print_success "Plugin verified: $entry"
+    else
+        print_error "Installation failed: entry point not found at $entry"
+        echo "  Expected: $entry"
+        echo "  Check the installation directory: $INSTALL_DIR"
+        exit 1
+    fi
+}
+
+show_summary() {
+    echo ""
+    echo -e "${GREEN}${BOLD}========================================${NC}"
+    echo -e "${GREEN}${BOLD}  Installation Complete!${NC}"
+    echo -e "${GREEN}${BOLD}========================================${NC}"
+    echo ""
+    echo "  Type:     $INSTALL_TYPE"
+    echo "  Location: $INSTALL_DIR"
+    echo ""
+    echo "  Next steps:"
+    echo "    1. Start opencode: opencode"
+    echo "    2. List sprints:   forloopSprintList"
+    echo "    3. Create a story: forloopStoryCreate --title 'My feature'"
+    echo ""
+    echo "  Docs: https://github.com/forloop-cc/forloop-opencode-plugin-planner"
+    echo ""
+}
+
+# ── Main ─────────────────────────────────────────────────────────────────────
+
+# Parse CLI flags
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        -g|--global)    INSTALL_TYPE="global"; shift ;;
+        -l|--local)     INSTALL_TYPE="local"; shift ;;
+        -d|--dir)
+            [ -z "${2:-}" ] && { print_error "--dir requires a path"; exit 1; }
+            INSTALL_TYPE="custom"; INSTALL_DIR="$2"; shift 2 ;;
+        -n|--npm)       USE_NPM=true; shift ;;
+        -b|--branch)
+            [ -z "${2:-}" ] && { print_error "--branch requires a name"; exit 1; }
+            BRANCH="$2"; shift 2 ;;
+        -f|--force)     FORCE=true; shift ;;
+        -h|--help)      show_help; exit 0 ;;
+        *)              print_error "Unknown option: $1"; show_help; exit 1 ;;
+    esac
+done
+
+# Detect non-interactive mode (stdin is a pipe, not terminal)
+if [ ! -t 0 ]; then
+    NON_INTERACTIVE=true
+    if [ -z "$INSTALL_TYPE" ]; then
+        print_info "Running in non-interactive mode, defaulting to local install"
+        INSTALL_TYPE="local"
+    fi
+fi
+
+print_header
+
+# Interactive: prompt for install type if not given
+if [ -z "$INSTALL_TYPE" ] && [ "$NON_INTERACTIVE" != true ]; then
+    prompt_install_type
+fi
+[ -z "$INSTALL_TYPE" ] && { print_error "Installation type required"; exit 1; }
+
+resolve_install_dir
+check_all_deps
+check_opencode
+
+if [ "$USE_NPM" = true ]; then
+    install_via_npm
+else
+    install_via_git
+fi
+
+merge_plugin_into_config
+setup_token
+verify_installation
+show_summary
+```
+
+- [ ] **Step 2: Set executable permissions**
+
+```bash
+chmod +x forloop-opencode-plugin-planner/install.sh
+```
+
+- [ ] **Step 3: Dry-run test — check the script is valid bash**
+
+```bash
+bash -n forloop-opencode-plugin-planner/install.sh
+```
+
+Expected: No syntax errors.
+
+- [ ] **Step 4: Test --help flag**
+
+```bash
+bash forloop-opencode-plugin-planner/install.sh --help
+```
+
+Expected: Help text printed with all flags listed.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add forloop-opencode-plugin-planner/install.sh
+git commit -m "feat: rewrite install.sh with npm/git support, jq config merge, non-interactive mode"
+```
+
+---
+
+### Task 2: Rewrite `update.sh`
+
+**Files:**
+- Rewrite: `forloop-opencode-plugin-planner/update.sh`
+
+- [ ] **Step 1: Write the update.sh script**
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ForLoop Plugin Updater
+# https://github.com/forloop-cc/forloop-opencode-plugin-planner
+#
+# Usage:
+#   curl -fsSL https://raw.githubusercontent.com/forloop-cc/forloop-opencode-plugin-planner/main/update.sh | bash
+#   bash update.sh --force --changelog
+#   bash update.sh --dir ~/my-custom-install
+
+# ── Colors ───────────────────────────────────────────────────────────────────
+PLATFORM="$(uname -s)"
+if [[ "$PLATFORM" =~ MINGW|MSYS|CYGWIN ]] && [ -z "$WT_SESSION" ] && [ -z "$ConEmuPID" ]; then
+    RED=''; GREEN=''; YELLOW=''; BLUE=''; CYAN=''; BOLD=''; NC=''
+else
+    RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'
+    BLUE='\033[0;34m'; CYAN='\033[0;36m'; BOLD='\033[1m'; NC='\033[0m'
+fi
+
+# ── Configuration ────────────────────────────────────────────────────────────
+PLUGIN_DIRNAME="forloop-planner"
+GLOBAL_INSTALL_DIR="$HOME/.config/opencode/plugins/$PLUGIN_DIRNAME"
+LOCAL_INSTALL_DIR=".opencode/plugins/$PLUGIN_DIRNAME"
+
+PLUGIN_DIR=""
+FORCE=false
+SHOW_CHANGELOG=false
+
+print_success() { echo -e "${GREEN}✓${NC} $1"; }
+print_info()    { echo -e "${BLUE}ℹ${NC} $1"; }
+print_warning() { echo -e "${YELLOW}⚠${NC} $1"; }
+print_error()   { echo -e "${RED}✗${NC} $1" >&2; }
+print_step()    { echo -e "\n${CYAN}${BOLD}▶${NC} $1\n"; }
+
+show_help() {
+    cat << EOF
+Usage: update.sh [OPTIONS]
+
+Options:
+  -d, --dir PATH     Update a specific install directory
+  -f, --force        Pull even if already up to date
+  -c, --changelog    Show recent changelog after update
+  -h, --help         Show this help
+
+Auto-detection order:
+  1. --dir flag
+  2. FORLOOP_PLUGIN_DIR env var
+  3. ./.opencode/plugins/forloop-planner/
+  4. ~/.config/opencode/plugins/forloop-planner/
+EOF
+}
+
+# ── Auto-detection ───────────────────────────────────────────────────────────
+
+find_installation() {
+    # 1. Check env var
+    if [ -n "${FORLOOP_PLUGIN_DIR:-}" ] && [ -d "$FORLOOP_PLUGIN_DIR/.git" ]; then
+        PLUGIN_DIR="$FORLOOP_PLUGIN_DIR"
+        print_info "Found via FORLOOP_PLUGIN_DIR: $PLUGIN_DIR"
+        return 0
+    fi
+
+    # 2. Check local
+    if [ -d "$LOCAL_INSTALL_DIR/.git" ]; then
+        PLUGIN_DIR="$LOCAL_INSTALL_DIR"
+        print_info "Found local install: $PLUGIN_DIR"
+        return 0
+    fi
+
+    # 3. Check global
+    if [ -d "$GLOBAL_INSTALL_DIR/.git" ]; then
+        PLUGIN_DIR="$GLOBAL_INSTALL_DIR"
+        print_info "Found global install: $PLUGIN_DIR"
+        return 0
+    fi
+
+    print_error "No ForLoop plugin installation found"
+    echo ""
+    echo "  Checked:"
+    echo "    1. FORLOOP_PLUGIN_DIR env var"
+    echo "    2. $LOCAL_INSTALL_DIR"
+    echo "    3. $GLOBAL_INSTALL_DIR"
+    echo ""
+    echo "  Specify location: bash update.sh --dir <path>"
+    echo "  Or install first:  curl -fsSL .../install.sh | bash"
+    return 1
+}
+
+# ── Update logic ─────────────────────────────────────────────────────────────
+
+update_via_git() {
+    print_step "Checking for updates..."
+    cd "$PLUGIN_DIR"
+
+    local current
+    current="$(git rev-parse --short HEAD)"
+
+    # Ensure on main branch
+    local branch
+    branch="$(git rev-parse --abbrev-ref HEAD)"
+    if [ "$branch" != "main" ] && [ "$branch" != "master" ]; then
+        print_info "Switching from '$branch' to main"
+        git checkout main --quiet 2>/dev/null || git checkout master --quiet 2>/dev/null || true
+    fi
+
+    git fetch origin --quiet
+
+    local remote
+    remote="$(git rev-parse --short origin/main 2>/dev/null || git rev-parse --short origin/master 2>/dev/null)"
+
+    if [ "$current" = "$remote" ] && [ "$FORCE" != true ]; then
+        print_success "Already up to date ($current)"
+        return 0
+    fi
+
+    print_info "Updating: $current → $remote"
+    git pull --quiet origin main 2>/dev/null || git pull --quiet origin master 2>/dev/null
+
+    # Reinstall dependencies
+    print_step "Installing dependencies..."
+    npm install --omit=dev --silent
+    print_success "Dependencies updated"
+
+    local new_ver
+    new_ver="$(git rev-parse --short HEAD)"
+    print_success "Updated to: $new_ver"
+}
+
+update_via_npm() {
+    print_step "Updating via npm..."
+    cd "$PLUGIN_DIR"
+
+    local before
+    before="$(npm list @forloop/opencode-plugin-planner --depth=0 2>/dev/null || echo 'unknown')"
+
+    npm update @forloop/opencode-plugin-planner --silent
+
+    local after
+    after="$(npm list @forloop/opencode-plugin-planner --depth=0 2>/dev/null || echo 'updated')"
+
+    print_success "$after"
+}
+
+# ── Changelog ────────────────────────────────────────────────────────────────
+
+show_recent_changelog() {
+    local changelog="$PLUGIN_DIR/CHANGELOG.md"
+    if [ -f "$changelog" ]; then
+        echo ""
+        print_info "Recent changes:"
+        echo "────────────────────────────────────────────"
+        head -60 "$changelog" | head -40
+        echo "────────────────────────────────────────────"
+    else
+        print_warning "No CHANGELOG.md found"
+    fi
+}
+
+# ── Verification ─────────────────────────────────────────────────────────────
+
+verify_update() {
+    local entry="$PLUGIN_DIR/plugins/forloop-plugin.ts"
+    if [ -f "$entry" ]; then
+        print_success "Plugin verified: $entry"
+    else
+        print_error "Update may have failed — entry point not found: $entry"
+        exit 1
+    fi
+}
+
+# ── Main ─────────────────────────────────────────────────────────────────────
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        -d|--dir)
+            [ -z "${2:-}" ] && { print_error "--dir requires a path"; exit 1; }
+            PLUGIN_DIR="$2"; shift 2 ;;
+        -f|--force)     FORCE=true; shift ;;
+        -c|--changelog) SHOW_CHANGELOG=true; shift ;;
+        -h|--help)      show_help; exit 0 ;;
+        *)              print_error "Unknown option: $1"; show_help; exit 1 ;;
+    esac
+done
+
+echo ""
+echo -e "${BLUE}${BOLD}╔══════════════════════════════════════════╗"
+echo -e "║       ForLoop Plugin Updater             ║"
+echo -e "╚══════════════════════════════════════════╝${NC}"
+echo ""
+
+if [ -z "$PLUGIN_DIR" ]; then
+    find_installation || exit 1
+fi
+
+if [ ! -d "$PLUGIN_DIR" ]; then
+    print_error "Plugin directory not found: $PLUGIN_DIR"
+    exit 1
+fi
+
+# Detect install method
+if [ -d "$PLUGIN_DIR/.git" ]; then
+    update_via_git
+elif [ -f "$PLUGIN_DIR/package.json" ]; then
+    update_via_npm
+else
+    print_error "Not a valid ForLoop plugin installation: $PLUGIN_DIR"
+    exit 1
+fi
+
+if [ "$SHOW_CHANGELOG" = true ]; then
+    show_recent_changelog
+fi
+
+verify_update
+
+echo ""
+print_success "Update complete!"
+echo "  Location: $PLUGIN_DIR"
+echo ""
+```
+
+- [ ] **Step 2: Set executable permissions**
+
+```bash
+chmod +x forloop-opencode-plugin-planner/update.sh
+```
+
+- [ ] **Step 3: Syntax check**
+
+```bash
+bash -n forloop-opencode-plugin-planner/update.sh
+```
+
+Expected: No syntax errors.
+
+- [ ] **Step 4: Test --help flag**
+
+```bash
+bash forloop-opencode-plugin-planner/update.sh --help
+```
+
+Expected: Help text with all flags and auto-detection order.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add forloop-opencode-plugin-planner/update.sh
+git commit -m "feat: rewrite update.sh with auto-detection, npm support, changelog display"
+```
+
+---
+
+### Task 3: Update `package.json` for npm publishing
+
+**Files:**
+- Modify: `forloop-opencode-plugin-planner/package.json`
+
+- [ ] **Step 1: Read current package.json to verify current state**
+
+```bash
+cat forloop-opencode-plugin-planner/package.json | jq '.name, .version, .main'
+```
+
+Expected: Shows current name, version, main entry.
+
+- [ ] **Step 2: Add `files` field to package.json**
+
+Location: After the `"license"` line, before `"repository"`. The `files` field ensures only distributable files are published to npm.
+
+Edit `forloop-opencode-plugin-planner/package.json`, adding these fields:
+
+```json
+  "main": "./plugins/forloop-plugin.ts",
+  "files": [
+    "plugins/",
+    "skills/",
+    "agents/",
+    "scripts/migrate-tokens.js",
+    "scripts/use-prod.sh",
+    "docs/",
+    "install.sh",
+    "update.sh",
+    "opencode.json",
+    "tsconfig.json",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "CODE_OF_CONDUCT.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+```
+
+- [ ] **Step 3: Verify the files field with npm pack (dry run)**
+
+```bash
+cd forloop-opencode-plugin-planner && npm pack --dry-run 2>&1 | head -30
+```
+
+Expected: Shows only the files listed above. No test/, .github/, .gitignore, node_modules/, etc.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add forloop-opencode-plugin-planner/package.json
+git commit -m "feat: add files field for npm publishing"
+```
+
+---
+
+### Task 4: End-to-End Verification
+
+**Files:**
+- No file changes — manual testing run
+
+- [ ] **Step 1: Create a temporary test directory**
+
+```bash
+mkdir -p /tmp/forloop-install-test && cd /tmp/forloop-install-test
+```
+
+- [ ] **Step 2: Test local install (simulating curl-pipe)**
+
+```bash
+bash /Users/toshilam/Documents/projects/phase4-opencode-plugin-planner/forloop-opencode-plugin-planner/install.sh --local --force
+```
+
+Expected:
+- Clones repo to `./.opencode/plugins/forloop-planner/`
+- Runs `npm install --omit=dev`
+- Creates `opencode.json` with plugin path
+- Verifies `plugins/forloop-plugin.ts` exists
+- Outputs success summary
+
+- [ ] **Step 3: Verify the installed files**
+
+```bash
+ls .opencode/plugins/forloop-planner/plugins/forloop-plugin.ts && echo "EXISTS"
+ls .opencode/plugins/forloop-planner/agents/forLoopPlanner.md && echo "EXISTS"
+ls .opencode/plugins/forloop-planner/skills/ && echo "DIR"
+ls .opencode/plugins/forloop-planner/node_modules/@opencode-ai/plugin && echo "DEPS"
+```
+
+Expected: All files and dependencies present.
+
+- [ ] **Step 4: Verify config merge correctness**
+
+```bash
+cat opencode.json | jq '.plugin'
+```
+
+Expected: Contains `"file://./.opencode/plugins/forloop-planner"`.
+
+- [ ] **Step 5: Test update (no changes expected)**
+
+```bash
+bash /Users/toshilam/Documents/projects/phase4-opencode-plugin-planner/forloop-opencode-plugin-planner/update.sh --dir ./.opencode/plugins/forloop-planner
+```
+
+Expected: "Already up to date" or similar.
+
+- [ ] **Step 6: Test --force update**
+
+```bash
+bash /Users/toshilam/Documents/projects/phase4-opencode-plugin-planner/forloop-opencode-plugin-planner/update.sh --dir ./.opencode/plugins/forloop-planner --force
+```
+
+Expected: Runs git pull + npm install even if current.
+
+- [ ] **Step 7: Clean up**
+
+```bash
+rm -rf /tmp/forloop-install-test
+```