Plannotator

#!/bin/bash
# plannotator - Status Check Script
# Verifies CLI install, hook configuration for all AI tools, and environment variables
#
# Usage: ./check-status.sh

RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
GRAY='\033[0;37m'
NC='\033[0m'

PASS=0
WARN=0
FAIL=0

check_pass() { echo -e "  ${GREEN}✓${NC} $1"; PASS=$((PASS+1)); }
check_warn() { echo -e "  ${YELLOW}⚠${NC} $1"; WARN=$((WARN+1)); }
check_fail() { echo -e "  ${RED}✗${NC} $1"; FAIL=$((FAIL+1)); }

echo ""
echo -e "${BLUE}╔════════════════════════════════════════════╗${NC}"
echo -e "${BLUE}║     plannotator Status Report              ║${NC}"
echo -e "${BLUE}╚════════════════════════════════════════════╝${NC}"
echo ""

# ── 1. CLI ─────────────────────────────────────────
echo -e "${BLUE}CLI Installation${NC}"

if command -v plannotator &>/dev/null; then
  VERSION=$(plannotator --version 2>/dev/null || echo "unknown")
  check_pass "plannotator CLI installed (version: ${VERSION})"
  check_pass "Location: $(which plannotator)"
else
  check_fail "plannotator CLI not found in PATH"
  echo -e "    ${GRAY}Fix: run ./install.sh${NC}"
fi

echo ""

# ── 2. Hook Configuration ──────────────────────────
echo -e "${BLUE}Hook Configuration${NC}"

SETTINGS_FILE="$HOME/.claude/settings.json"
HOOK_CONFIGURED=false

if [ -f "$SETTINGS_FILE" ]; then
  if grep -q "plannotator" "$SETTINGS_FILE" 2>/dev/null; then
    check_pass "plannotator hook found in ~/.claude/settings.json"
    HOOK_CONFIGURED=true

    # Check hook is for ExitPlanMode
    if grep -q "ExitPlanMode" "$SETTINGS_FILE" 2>/dev/null; then
      check_pass "Hook is bound to ExitPlanMode (plan review enabled)"
    else
      check_warn "Hook found but not bound to ExitPlanMode"
    fi
  else
    check_warn "No plannotator hook in ~/.claude/settings.json"
    echo -e "    ${GRAY}Fix: run ./setup-hook.sh${NC}"
  fi
else
  check_warn "~/.claude/settings.json not found"
  echo -e "    ${GRAY}Fix: run ./setup-hook.sh to create it${NC}"
fi

# Check for plugin install (alternative to manual hook)
PLUGIN_DIR="$HOME/.claude/plugins"
if [ -d "$PLUGIN_DIR" ] && ls "$PLUGIN_DIR" 2>/dev/null | grep -qi plannotator; then
  check_pass "plannotator Claude Code plugin detected"
  HOOK_CONFIGURED=true
fi

if [ "$HOOK_CONFIGURED" = false ]; then
  check_fail "No hook configuration found — plan review won't trigger automatically"
  echo -e "    ${GRAY}Fix: run ./setup-hook.sh${NC}"
fi

echo ""

# ── 3. Environment Variables ───────────────────────
echo -e "${BLUE}Environment Variables${NC}"

if [ -n "$PLANNOTATOR_REMOTE" ]; then
  check_pass "PLANNOTATOR_REMOTE=${PLANNOTATOR_REMOTE} (remote mode active)"
else
  echo -e "  ${GRAY}-${NC} PLANNOTATOR_REMOTE not set (local mode — browser opens automatically)"
fi

if [ -n "$PLANNOTATOR_PORT" ]; then
  check_pass "PLANNOTATOR_PORT=${PLANNOTATOR_PORT}"
else
  echo -e "  ${GRAY}-${NC} PLANNOTATOR_PORT not set (random port in local mode, 19432 in remote mode)"
fi

if [ -n "$PLANNOTATOR_BROWSER" ]; then
  check_pass "PLANNOTATOR_BROWSER=${PLANNOTATOR_BROWSER}"
else
  echo -e "  ${GRAY}-${NC} PLANNOTATOR_BROWSER not set (uses system default)"
fi

if [ -n "$PLANNOTATOR_SHARE_URL" ]; then
  check_pass "PLANNOTATOR_SHARE_URL=${PLANNOTATOR_SHARE_URL}"
else
  echo -e "  ${GRAY}-${NC} PLANNOTATOR_SHARE_URL not set (uses share.plannotator.ai)"
fi

echo ""

# ── 4. Review Command ──────────────────────────────
echo -e "${BLUE}Code Review (/plannotator-review)${NC}"

if command -v plannotator &>/dev/null; then
  # Try to check if review subcommand exists
  if plannotator review --help &>/dev/null 2>&1; then
    check_pass "plannotator review command available"
  else
    check_warn "plannotator review command may not be available (check CLI version)"
  fi
else
  check_fail "Cannot check review command — CLI not installed"
fi

echo ""

# ── 3b. Gemini CLI Hook ─────────────────────────────────────
echo -e "${BLUE}Gemini CLI Hook${NC}"

GEMINI_SETTINGS="$HOME/.gemini/settings.json"
if [ -f "$GEMINI_SETTINGS" ]; then
  if grep -q "plannotator" "$GEMINI_SETTINGS" 2>/dev/null; then
    check_pass "plannotator hook found in ~/.gemini/settings.json"
    if grep -q "ExitPlanMode" "$GEMINI_SETTINGS" 2>/dev/null; then
      check_pass "Hook bound to ExitPlanMode"
    else
      check_warn "Hook found but not bound to ExitPlanMode"
    fi
  else
    check_warn "No plannotator hook in ~/.gemini/settings.json"
    echo -e "    ${GRAY}Fix: run ./setup-gemini-hook.sh${NC}"
  fi
else
  echo -e "  ${GRAY}-${NC} ~/.gemini/settings.json not found (run ./setup-gemini-hook.sh to configure)"
fi

GEMINI_MD="$HOME/.gemini/GEMINI.md"
if [ -f "$GEMINI_MD" ] && grep -q "plannotator" "$GEMINI_MD" 2>/dev/null; then
  check_pass "plannotator instructions found in ~/.gemini/GEMINI.md"
else
  echo -e "  ${GRAY}-${NC} No plannotator instructions in GEMINI.md (run ./setup-gemini-hook.sh)"
fi

echo ""

# ── 3c. Codex CLI Configuration ────────────────────────────
echo -e "${BLUE}Codex CLI Configuration${NC}"

CODEX_CONFIG="$HOME/.codex/config.toml"
if [ -f "$CODEX_CONFIG" ]; then
  if grep -q "plannotator" "$CODEX_CONFIG" 2>/dev/null; then
    check_pass "plannotator found in ~/.codex/config.toml developer_instructions"
  else
    check_warn "No plannotator reference in ~/.codex/config.toml"
    echo -e "    ${GRAY}Fix: run ./setup-codex-hook.sh${NC}"
  fi
else
  echo -e "  ${GRAY}-${NC} ~/.codex/config.toml not found (run ./setup-codex-hook.sh to configure)"
fi

CODEX_PROMPT="$HOME/.codex/prompts/plannotator.md"
if [ -f "$CODEX_PROMPT" ]; then
  check_pass "plannotator prompt file found at ~/.codex/prompts/plannotator.md"
else
  echo -e "  ${GRAY}-${NC} No plannotator prompt at ~/.codex/prompts/ (run ./setup-codex-hook.sh)"
fi

echo ""

# ── 3d. OpenCode Plugin ─────────────────────────────────────
echo -e "${BLUE}OpenCode Plugin${NC}"

OPENCODE_COMMAND_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/opencode/command"
OPENCODE_JSON_FOUND=false

for candidate in "${PWD}/opencode.json" "$HOME/.config/opencode/opencode.json" "$HOME/opencode.json"; do
  if [ -f "$candidate" ] && grep -q "plannotator" "$candidate" 2>/dev/null; then
    check_pass "plannotator plugin found in ${candidate}"
    OPENCODE_JSON_FOUND=true
    break
  fi
done

if [ "$OPENCODE_JSON_FOUND" = false ]; then
  echo -e "  ${GRAY}-${NC} No plannotator plugin in opencode.json (run ./setup-opencode-plugin.sh)"
fi

if [ -f "${OPENCODE_COMMAND_DIR}/plannotator-review.md" ]; then
  check_pass "/plannotator-review slash command registered"
else
  echo -e "  ${GRAY}-${NC} /plannotator-review not found (run ./setup-opencode-plugin.sh)"
fi

if [ -f "${OPENCODE_COMMAND_DIR}/plannotator-annotate.md" ]; then
  check_pass "/plannotator-annotate slash command registered"
else
  echo -e "  ${GRAY}-${NC} /plannotator-annotate not found (run ./setup-opencode-plugin.sh)"
fi

echo ""

# ── 3e. Obsidian ────────────────────────────────────────────
echo -e "${BLUE}Obsidian (Optional — for plan auto-save)${NC}"

if command -v obsidian &>/dev/null 2>&1 || [ -d "/Applications/Obsidian.app" ] || [ -d "$HOME/Applications/Obsidian.app" ]; then
  check_pass "Obsidian detected"
else
  echo -e "  ${GRAY}-${NC} Obsidian not found (install: ${BLUE}https://obsidian.md/download${NC})"
  echo -e "  ${GRAY}   Enable vault sync in plannotator UI → gear icon → Obsidian Integration${NC}"
fi

echo ""

echo -e "${BLUE}Bear Notes (Optional — for plan auto-save)${NC}"

if [ -d "/Applications/Bear.app" ] || [ -d "$HOME/Applications/Bear.app" ]; then
  check_pass "Bear.app detected"
  echo -e "  ${GRAY}-${NC} Quick check: ${GREEN}open \"bear://x-callback-url/create?title=Plannotator%20Check&text=ok\"${NC}"
else
  echo -e "  ${GRAY}-${NC} Bear.app not found (install from App Store)"
  echo -e "  ${GRAY}   Bear export uses ${BLUE}bear://x-callback-url/create${NC} in system browser${NC}"
fi

echo ""

# ── 5. Git Status ──────────────────────────────────────────
echo -e "${BLUE}Git Repository${NC}"

if git rev-parse --git-dir &>/dev/null 2>&1; then
  BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
  check_pass "Git repository detected (branch: ${BRANCH})"

  DIFF_COUNT=$(git diff --shortstat 2>/dev/null | grep -oE '[0-9]+ file' | head -1 || echo "0 file")
  if [ "$DIFF_COUNT" != "0 file" ]; then
    check_pass "Uncommitted changes found — ready for /plannotator-review"
  else
    echo -e "  ${GRAY}-${NC} No uncommitted changes (commit some code first for diff review)"
  fi
else
  check_warn "Not in a git repository — diff review won't work"
fi

echo ""

# ── Summary ────────────────────────────────────────
echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
echo ""
echo -e "  ${GREEN}Passed:${NC}   ${PASS}"
[ $WARN -gt 0 ] && echo -e "  ${YELLOW}Warnings:${NC} ${WARN}"
[ $FAIL -gt 0 ] && echo -e "  ${RED}Failed:${NC}   ${FAIL}"
echo ""

if [ $FAIL -eq 0 ] && [ $WARN -eq 0 ]; then
  echo -e "${GREEN}All checks passed — plannotator is ready!${NC}"
elif [ $FAIL -eq 0 ]; then
  echo -e "${YELLOW}Setup is mostly complete — check warnings above${NC}"
else
  echo -e "${RED}Setup incomplete — fix the failures above before using plannotator${NC}"
fi

echo ""
echo -e "${BLUE}Setup scripts available:${NC}"
echo -e "  ${GREEN}./setup-hook.sh${NC}            Claude Code hook"
echo -e "  ${GREEN}./setup-gemini-hook.sh${NC}     Gemini CLI hook"
echo -e "  ${GREEN}./setup-codex-hook.sh${NC}      Codex CLI"
echo -e "  ${GREEN}./setup-opencode-plugin.sh${NC} OpenCode plugin"
echo -e "  ${GREEN}./install.sh --all${NC}         All integrations at once"
echo ""

#!/bin/bash
# plannotator - Remote / Devcontainer Configuration Script
# Sets up environment variables for SSH, devcontainer, or WSL usage.
#
# Usage:
#   ./configure-remote.sh              # Interactive
#   ./configure-remote.sh --port 9999  # Set port only
#   ./configure-remote.sh --show       # Show current config

RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
GRAY='\033[0;37m'
NC='\033[0m'

SHOW_ONLY=false
PORT=""
SHELL_PROFILE=""

for arg in "$@"; do
  case $arg in
    --show) SHOW_ONLY=true ;;
    --port) PORT="$2"; shift ;;
    --port=*) PORT="${arg#*=}" ;;
    -h|--help)
      echo "Usage: $0 [--show] [--port <number>]"
      echo ""
      echo "Configures plannotator for remote/devcontainer environments."
      echo ""
      echo "Options:"
      echo "  --show         Display current plannotator environment variables"
      echo "  --port <n>     Set PLANNOTATOR_PORT to <n>"
      echo "  -h, --help     Show this help"
      exit 0
      ;;
  esac
done

echo ""
echo -e "${BLUE}╔════════════════════════════════════════════╗${NC}"
echo -e "${BLUE}║   plannotator Remote Configuration         ║${NC}"
echo -e "${BLUE}╚════════════════════════════════════════════╝${NC}"
echo ""

# ── Show current config ────────────────────────────
show_config() {
  echo -e "${BLUE}Current plannotator environment:${NC}"
  echo ""

  if [ -n "$PLANNOTATOR_REMOTE" ]; then
    echo -e "  PLANNOTATOR_REMOTE   = ${GREEN}${PLANNOTATOR_REMOTE}${NC}"
  else
    echo -e "  PLANNOTATOR_REMOTE   = ${GRAY}(not set — local mode)${NC}"
  fi

  if [ -n "$PLANNOTATOR_PORT" ]; then
    echo -e "  PLANNOTATOR_PORT     = ${GREEN}${PLANNOTATOR_PORT}${NC}"
  else
    echo -e "  PLANNOTATOR_PORT     = ${GRAY}(not set — random in local, 19432 in remote)${NC}"
  fi

  if [ -n "$PLANNOTATOR_BROWSER" ]; then
    echo -e "  PLANNOTATOR_BROWSER  = ${GREEN}${PLANNOTATOR_BROWSER}${NC}"
  else
    echo -e "  PLANNOTATOR_BROWSER  = ${GRAY}(not set — system default)${NC}"
  fi

  if [ -n "$PLANNOTATOR_SHARE_URL" ]; then
    echo -e "  PLANNOTATOR_SHARE_URL= ${GREEN}${PLANNOTATOR_SHARE_URL}${NC}"
  else
    echo -e "  PLANNOTATOR_SHARE_URL= ${GRAY}(not set — share.plannotator.ai)${NC}"
  fi

  echo ""
}

show_config

if [ "$SHOW_ONLY" = true ]; then
  exit 0
fi

# ── Detect shell profile ───────────────────────────
detect_profile() {
  if [ -n "$ZSH_VERSION" ] || [ "$(basename "$SHELL")" = "zsh" ]; then
    echo "$HOME/.zshrc"
  elif [ -n "$BASH_VERSION" ] || [ "$(basename "$SHELL")" = "bash" ]; then
    if [ -f "$HOME/.bash_profile" ]; then
      echo "$HOME/.bash_profile"
    else
      echo "$HOME/.bashrc"
    fi
  else
    echo "$HOME/.profile"
  fi
}

SHELL_PROFILE=$(detect_profile)

echo -e "${BLUE}Shell profile detected:${NC} ${SHELL_PROFILE}"
echo ""

# ── Interactive prompts ────────────────────────────
echo -e "${BLUE}Configure plannotator for remote use?${NC}"
echo ""
echo -e "  ${YELLOW}Remote mode${NC} disables auto browser open and uses a fixed port."
echo -e "  Use this when running Claude Code via SSH, devcontainer, or WSL."
echo ""
read -rp "Enable remote mode? [y/N]: " ENABLE_REMOTE
echo ""

LINES_TO_ADD=""

if [[ "$ENABLE_REMOTE" =~ ^[Yy]$ ]]; then
  LINES_TO_ADD="${LINES_TO_ADD}export PLANNOTATOR_REMOTE=1\n"
  echo -e "${GREEN}✓ Remote mode will be enabled${NC}"

  # Port
  if [ -z "$PORT" ]; then
    read -rp "Port to use [default: 19432]: " PORT
    PORT="${PORT:-19432}"
  fi
  LINES_TO_ADD="${LINES_TO_ADD}export PLANNOTATOR_PORT=${PORT}\n"
  echo -e "${GREEN}✓ Port set to ${PORT}${NC}"
  echo ""

  echo -e "${BLUE}Port forwarding setup:${NC}"
  echo ""
  echo -e "  ${GRAY}SSH config (~/.ssh/config):${NC}"
  echo -e "    Host your-server"
  echo -e "      LocalForward ${PORT} localhost:${PORT}"
  echo ""
  echo -e "  ${GRAY}VS Code devcontainer: check the 'Ports' tab (auto-forwarded)${NC}"
  echo ""
else
  # Local mode — optionally set custom browser
  read -rp "Custom browser path/app? (leave empty for default): " CUSTOM_BROWSER
  if [ -n "$CUSTOM_BROWSER" ]; then
    LINES_TO_ADD="${LINES_TO_ADD}export PLANNOTATOR_BROWSER=\"${CUSTOM_BROWSER}\"\n"
    echo -e "${GREEN}✓ Browser set to: ${CUSTOM_BROWSER}${NC}"
  fi
fi

# Share URL
read -rp "Custom share URL? (leave empty for share.plannotator.ai): " CUSTOM_SHARE
if [ -n "$CUSTOM_SHARE" ]; then
  LINES_TO_ADD="${LINES_TO_ADD}export PLANNOTATOR_SHARE_URL=\"${CUSTOM_SHARE}\"\n"
  echo -e "${GREEN}✓ Share URL set to: ${CUSTOM_SHARE}${NC}"
fi

echo ""

if [ -z "$LINES_TO_ADD" ]; then
  echo -e "${YELLOW}No changes to make.${NC}"
  exit 0
fi

# ── Write to shell profile ─────────────────────────
echo -e "${BLUE}Adding to ${SHELL_PROFILE}:${NC}"
echo ""
printf "  %b" "$LINES_TO_ADD" | sed 's/^/  /'
echo ""

read -rp "Write to ${SHELL_PROFILE}? [Y/n]: " CONFIRM
if [[ "$CONFIRM" =~ ^[Nn]$ ]]; then
  echo ""
  echo -e "${YELLOW}Not written. Add these lines manually to your shell profile:${NC}"
  echo ""
  printf "%b" "$LINES_TO_ADD"
  exit 0
fi

{
  echo ""
  echo "# plannotator configuration"
  printf "%b" "$LINES_TO_ADD"
} >> "$SHELL_PROFILE"

echo ""
echo -e "${GREEN}✓ Configuration written to ${SHELL_PROFILE}${NC}"
echo ""
echo -e "${BLUE}Apply now with:${NC}"
echo -e "  source ${SHELL_PROFILE}"
echo ""
echo -e "${BLUE}Verify with:${NC}"
echo -e "  ./check-status.sh"
echo ""

#!/bin/bash
# plannotator - Installation Script
# Installs the plannotator CLI and optionally sets up AI tool integrations
#
# Usage:
#   ./install.sh                  # CLI only
#   ./install.sh --with-plugin    # CLI + Claude Code plugin
#   ./install.sh --with-gemini    # CLI + Gemini CLI hook
#   ./install.sh --with-codex     # CLI + Codex CLI setup
#   ./install.sh --with-opencode  # CLI + OpenCode plugin
#   ./install.sh --all            # CLI + all integrations

set -e

RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
GRAY='\033[0;37m'
NC='\033[0m'

WITH_PLUGIN=false
WITH_GEMINI=false
WITH_CODEX=false
WITH_OPENCODE=false

for arg in "$@"; do
  case $arg in
    --with-plugin)   WITH_PLUGIN=true ;;
    --with-gemini)   WITH_GEMINI=true ;;
    --with-codex)    WITH_CODEX=true ;;
    --with-opencode) WITH_OPENCODE=true ;;
    --all)
      WITH_PLUGIN=true
      WITH_GEMINI=true
      WITH_CODEX=true
      WITH_OPENCODE=true
      ;;
    -h|--help)
      echo "Usage: $0 [OPTIONS]"
      echo ""
      echo "Options:"
      echo "  --with-plugin    Also output Claude Code plugin install commands"
      echo "  --with-gemini    Configure Gemini CLI hook (runs setup-gemini-hook.sh)"
      echo "  --with-codex     Configure Codex CLI (runs setup-codex-hook.sh)"
      echo "  --with-opencode  Register OpenCode plugin (runs setup-opencode-plugin.sh)"
      echo "  --all            All of the above"
      echo "  -h, --help       Show this help"
      echo ""
      echo "Prerequisites:"
      echo "  Obsidian (for plan/review auto-save): https://obsidian.md/download"
      exit 0
      ;;
  esac
done

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

echo ""
echo -e "${BLUE}╔════════════════════════════════════════════╗${NC}"
echo -e "${BLUE}║       plannotator Installer                ║${NC}"
echo -e "${BLUE}╚════════════════════════════════════════════╝${NC}"
echo ""

echo -e "${BLUE}━━ Prerequisites ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
echo ""
if command -v obsidian &>/dev/null 2>&1 || [ -d "/Applications/Obsidian.app" ] || [ -d "$HOME/Applications/Obsidian.app" ]; then
  echo -e "  ${GREEN}✓ Obsidian detected${NC}"
else
  echo -e "  ${YELLOW}⚠ Obsidian not detected${NC}"
  echo -e "  ${GRAY}  plannotator can auto-save approved plans to your Obsidian vault.${NC}"
  echo -e "  ${GRAY}  Install Obsidian: ${BLUE}https://obsidian.md/download${NC}"
  echo -e "  ${GRAY}  (You can skip this and enable later via plannotator UI → gear icon)${NC}"
fi
echo ""

OS=""
case "$(uname -s)" in
  Darwin) OS="macos" ;;
  Linux)
    if grep -qi microsoft /proc/version 2>/dev/null; then
      OS="wsl"
    else
      OS="linux"
    fi
    ;;
  CYGWIN*|MINGW*|MSYS*) OS="windows" ;;
  *) OS="unknown" ;;
esac

echo -e "${BLUE}━━ Installing plannotator CLI ━━━━━━━━━━━━━━━━━━━${NC}"
echo ""
echo -e "${BLUE}Detected OS:${NC} ${OS}"
echo ""

if command -v plannotator &>/dev/null; then
  CURRENT_VERSION=$(plannotator --version 2>/dev/null || echo "unknown")
  echo -e "${YELLOW}plannotator is already installed (version: ${CURRENT_VERSION})${NC}"
  echo -e "${GRAY}Re-running install to update to latest version...${NC}"
  echo ""
fi

case "$OS" in
  macos|linux|wsl)
    if curl -fsSL https://plannotator.ai/install.sh | bash; then
      echo ""
      echo -e "${GREEN}✓ plannotator CLI installed successfully${NC}"
    else
      echo -e "${RED}✗ Installation failed${NC}"
      echo -e "${YELLOW}Try manual install: curl -fsSL https://plannotator.ai/install.sh | bash${NC}"
      exit 1
    fi
    ;;
  windows)
    echo -e "${YELLOW}Windows detected. Run in PowerShell:${NC}"
    echo ""
    echo "    irm https://plannotator.ai/install.ps1 | iex"
    echo ""
    echo -e "${GRAY}Or for CMD:${NC}"
    echo "    curl -fsSL https://plannotator.ai/install.cmd -o install.cmd && install.cmd && del install.cmd"
    echo ""
    exit 0
    ;;
  *)
    echo -e "${RED}Unsupported OS. Visit https://plannotator.ai for manual install instructions.${NC}"
    exit 1
    ;;
esac

# Verify installation
echo ""
echo -e "${BLUE}Verifying installation...${NC}"

# Reload PATH in case plannotator was added to a new location
export PATH="$HOME/.local/bin:$HOME/bin:$PATH"

if command -v plannotator &>/dev/null; then
  VERSION=$(plannotator --version 2>/dev/null || echo "unknown")
  echo -e "${GREEN}✓ plannotator ${VERSION} is ready${NC}"
  echo -e "${GRAY}  Location: $(which plannotator)${NC}"
else
  echo -e "${YELLOW}⚠ plannotator installed but not in PATH${NC}"
  echo -e "${YELLOW}  Restart your terminal or run: source ~/.bashrc (or ~/.zshrc)${NC}"
fi

if [ "$WITH_PLUGIN" = true ]; then
  echo ""
  echo -e "${BLUE}━━ Claude Code Plugin Setup ━━━━━━━━━━━━━━━━━━━━━${NC}"
  echo ""
  echo -e "Run these commands inside Claude Code:"
  echo ""
  echo -e "  ${GREEN}/plugin marketplace add backnotprop/plannotator${NC}"
  echo -e "  ${GREEN}/plugin install plannotator@plannotator${NC}"
  echo ""
  echo -e "${YELLOW}⚠ IMPORTANT: Restart Claude Code after plugin install${NC}"
  echo ""
  echo -e "${GRAY}Alternative (manual hook): run ./setup-hook.sh${NC}"
fi

if [ "$WITH_GEMINI" = true ]; then
  echo ""
  echo -e "${BLUE}━━ Gemini CLI Integration ━━━━━━━━━━━━━━━━━━━━━━━${NC}"
  echo ""
  if [ -f "${SCRIPT_DIR}/setup-gemini-hook.sh" ]; then
    bash "${SCRIPT_DIR}/setup-gemini-hook.sh"
  else
    echo -e "${YELLOW}⚠ setup-gemini-hook.sh not found at ${SCRIPT_DIR}${NC}"
    echo -e "${GRAY}  Run it manually from the scripts/ directory${NC}"
  fi
fi

if [ "$WITH_CODEX" = true ]; then
  echo ""
  echo -e "${BLUE}━━ Codex CLI Integration ━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
  echo ""
  if [ -f "${SCRIPT_DIR}/setup-codex-hook.sh" ]; then
    bash "${SCRIPT_DIR}/setup-codex-hook.sh"
  else
    echo -e "${YELLOW}⚠ setup-codex-hook.sh not found at ${SCRIPT_DIR}${NC}"
    echo -e "${GRAY}  Run it manually from the scripts/ directory${NC}"
  fi
fi

if [ "$WITH_OPENCODE" = true ]; then
  echo ""
  echo -e "${BLUE}━━ OpenCode Plugin Integration ━━━━━━━━━━━━━━━━━━${NC}"
  echo ""
  if [ -f "${SCRIPT_DIR}/setup-opencode-plugin.sh" ]; then
    bash "${SCRIPT_DIR}/setup-opencode-plugin.sh"
  else
    echo -e "${YELLOW}⚠ setup-opencode-plugin.sh not found at ${SCRIPT_DIR}${NC}"
    echo -e "${GRAY}  Run it manually from the scripts/ directory${NC}"
  fi
fi

echo ""
echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
echo -e "${GREEN}Installation complete!${NC}"
echo ""
echo -e "${GRAY}Next steps:${NC}"

if [ "$WITH_PLUGIN" = false ] && [ "$WITH_GEMINI" = false ] && [ "$WITH_CODEX" = false ] && [ "$WITH_OPENCODE" = false ]; then
  echo -e "  ${BLUE}1.${NC} Run ${GREEN}./setup-hook.sh${NC} to configure Claude Code hooks"
  echo -e "  ${BLUE}   ${NC} Or run ${GREEN}./install.sh --all${NC} to set up all AI tool integrations"
  echo -e "  ${BLUE}2.${NC} Run ${GREEN}./check-status.sh${NC} to verify everything is working"
  echo -e "  ${BLUE}3.${NC} Install Obsidian for plan auto-save: ${BLUE}https://obsidian.md/download${NC}"
else
  echo -e "  ${BLUE}1.${NC} Run ${GREEN}./check-status.sh${NC} to verify all integrations"
  echo -e "  ${BLUE}2.${NC} Restart any AI tools that were configured above"
  if ! command -v obsidian &>/dev/null 2>&1 && [ ! -d "/Applications/Obsidian.app" ]; then
    echo -e "  ${BLUE}3.${NC} Install Obsidian for plan auto-save: ${BLUE}https://obsidian.md/download${NC}"
  fi
fi
echo ""

#!/bin/bash
# plannotator - Code Review (Diff Review) Script
# Opens a visual diff review of current git changes in the plannotator UI.
#
# Usage:
#   ./review.sh              # Review all uncommitted changes
#   ./review.sh HEAD~1       # Review last commit
#   ./review.sh main...HEAD  # Review changes from main to HEAD

RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
GRAY='\033[0;37m'
NC='\033[0m'

DIFF_REF="${1:-}"

echo ""
echo -e "${BLUE}╔════════════════════════════════════════════╗${NC}"
echo -e "${BLUE}║    plannotator Code Review                 ║${NC}"
echo -e "${BLUE}╚════════════════════════════════════════════╝${NC}"
echo ""

# Check CLI
if ! command -v plannotator &>/dev/null; then
  echo -e "${RED}✗ plannotator CLI not found${NC}"
  echo -e "${YELLOW}  Run ./install.sh first${NC}"
  exit 1
fi

# Check git repo
if ! git rev-parse --git-dir &>/dev/null 2>&1; then
  echo -e "${RED}✗ Not inside a git repository${NC}"
  exit 1
fi

# Show diff summary
echo -e "${BLUE}Repository:${NC} $(git rev-parse --show-toplevel 2>/dev/null)"
echo -e "${BLUE}Branch:${NC} $(git branch --show-current 2>/dev/null)"
echo ""

if [ -n "$DIFF_REF" ]; then
  echo -e "${BLUE}Diff target:${NC} ${DIFF_REF}"
  STAT=$(git diff --stat "$DIFF_REF" 2>/dev/null || git diff --stat "${DIFF_REF}..HEAD" 2>/dev/null)
else
  echo -e "${BLUE}Diff target:${NC} uncommitted changes (staged + unstaged)"
  STAT=$(git diff --stat HEAD 2>/dev/null)
  if [ -z "$STAT" ]; then
    STAT=$(git diff --stat 2>/dev/null)
  fi
fi

if [ -z "$STAT" ]; then
  echo -e "${YELLOW}⚠ No changes found to review${NC}"
  echo ""
  echo -e "${GRAY}Tips:${NC}"
  echo -e "  • Make some changes and run again"
  echo -e "  • Review a specific commit: ./review.sh HEAD~1"
  echo -e "  • Review branch diff: ./review.sh main...HEAD"
  exit 0
fi

echo ""
echo -e "${BLUE}Changes to review:${NC}"
echo "$STAT" | sed 's/^/  /'
echo ""

# Launch plannotator review
echo -e "${BLUE}Opening plannotator diff review UI...${NC}"
echo ""

if [ -n "$DIFF_REF" ]; then
  plannotator review "$DIFF_REF"
else
  plannotator review
fi

EXIT_CODE=$?

echo ""
if [ $EXIT_CODE -eq 0 ]; then
  echo -e "${GREEN}Review session complete${NC}"
else
  echo -e "${YELLOW}Review exited with code ${EXIT_CODE}${NC}"
  echo ""
  echo -e "${GRAY}If the browser didn't open, check:${NC}"
  echo -e "  • Is PLANNOTATOR_REMOTE=1 set? Access at http://localhost:${PLANNOTATOR_PORT:-19432}"
  echo -e "  • Run ${GREEN}./check-status.sh${NC} to diagnose"
fi

echo ""

#!/bin/bash
# plannotator - Codex CLI Setup Script
# Configures plannotator for Codex CLI by:
#   1. Adding developer_instructions to ~/.codex/config.toml
#   2. Creating a plannotator prompt at ~/.codex/prompts/plannotator.md
#
# Usage: ./setup-codex-hook.sh [--dry-run]

set -e

RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
GRAY='\033[0;37m'
NC='\033[0m'

DRY_RUN=false
for arg in "$@"; do
  case $arg in
    --dry-run) DRY_RUN=true ;;
    -h|--help)
      echo "Usage: $0 [--dry-run]"
      echo ""
      echo "Configures plannotator for Codex CLI:"
      echo "  1. Adds plannotator instructions to ~/.codex/config.toml developer_instructions"
      echo "  2. Creates ~/.codex/prompts/plannotator.md for agent role"
      echo ""
      echo "Options:"
      echo "  --dry-run   Show what would change without writing"
      echo "  -h, --help  Show this help"
      exit 0
      ;;
  esac
done

CODEX_DIR="$HOME/.codex"
CODEX_CONFIG="$CODEX_DIR/config.toml"
CODEX_PROMPTS="$CODEX_DIR/prompts"
PLANNOTATOR_PROMPT="$CODEX_PROMPTS/plannotator.md"

echo ""
echo -e "${BLUE}╔════════════════════════════════════════════╗${NC}"
echo -e "${BLUE}║  plannotator × Codex CLI Setup             ║${NC}"
echo -e "${BLUE}╚════════════════════════════════════════════╝${NC}"
echo ""

if ! command -v plannotator &>/dev/null; then
  echo -e "${RED}✗ plannotator CLI not found${NC}"
  echo -e "${YELLOW}  Run ./install.sh first${NC}"
  exit 1
fi
echo -e "${GREEN}✓ plannotator CLI is installed${NC}"
echo ""

if ! command -v codex &>/dev/null; then
  echo -e "${YELLOW}⚠ codex CLI not found in PATH${NC}"
  echo -e "${GRAY}  Install via: npm install -g @openai/codex${NC}"
  echo -e "${GRAY}  Continuing setup anyway...${NC}"
  echo ""
fi

mkdir -p "$CODEX_DIR" "$CODEX_PROMPTS"

# ════════════════════════════════════════════════════════════
# PART 1: developer_instructions in config.toml
# ════════════════════════════════════════════════════════════
echo -e "${BLUE}━━ Step 1: config.toml developer_instructions ━━━━${NC}"
echo ""

PLANNOTATOR_INSTRUCTION='Before implementing any plan, write the plan markdown to /tmp/plan.md and run: `python3 -c "import json; print(json.dumps({\"tool_input\": {\"plan\": open(\"/tmp/plan.md\").read(), \"permission_mode\": \"acceptEdits\"}}))" | plannotator > /tmp/pn_out.txt 2>&1 & sleep 5; cat /tmp/pn_out.txt`. Wait for user approval in plannotator UI. After coding, run `plannotator review` to open code review.'

if [ -f "$CODEX_CONFIG" ] && grep -q "plannotator" "$CODEX_CONFIG" 2>/dev/null; then
  echo -e "${YELLOW}⚠ plannotator already referenced in ${CODEX_CONFIG}${NC}"
  echo -e "${GRAY}  No changes made to config.toml.${NC}"
else
  if [ "$DRY_RUN" = true ]; then
    echo -e "${YELLOW}[DRY RUN] Would add to developer_instructions in ${CODEX_CONFIG}:${NC}"
    echo "  $PLANNOTATOR_INSTRUCTION"
  else
    if [ ! -f "$CODEX_CONFIG" ]; then
      cat > "$CODEX_CONFIG" <<EOF
developer_instructions = "${PLANNOTATOR_INSTRUCTION}"
EOF
      echo -e "${GREEN}✓ Created ${CODEX_CONFIG} with plannotator instructions${NC}"
    else
      BACKUP="${CODEX_CONFIG}.bak.$(date +%Y%m%d%H%M%S)"
      cp "$CODEX_CONFIG" "$BACKUP"
      echo -e "${GRAY}  Backup saved: ${BACKUP}${NC}"

      if grep -q "^developer_instructions" "$CODEX_CONFIG"; then
        if command -v python3 &>/dev/null; then
          python3 - "$CODEX_CONFIG" "$PLANNOTATOR_INSTRUCTION" <<'PYEOF'
import sys, re

path = sys.argv[1]
addition = sys.argv[2]

with open(path) as f:
    content = f.read()

pattern = r'^(developer_instructions\s*=\s*")(.+?)(")'
match = re.search(pattern, content, re.MULTILINE)

if match:
    current = match.group(2)
    if "plannotator" not in current:
        new_val = current + " " + addition
        content = content[:match.start()] + f'developer_instructions = "{new_val}"' + content[match.end():]
        with open(path, "w") as f:
            f.write(content)
        print("Appended to developer_instructions.")
    else:
        print("plannotator already in developer_instructions — no change.")
else:
    with open(path, "a") as f:
        f.write(f'\ndeveloper_instructions = "{addition}"\n')
    print("Added developer_instructions line.")
PYEOF
        else
          echo "developer_instructions = \"${PLANNOTATOR_INSTRUCTION}\"" >> "$CODEX_CONFIG"
        fi
        echo -e "${GREEN}✓ Updated developer_instructions in ${CODEX_CONFIG}${NC}"
      else
        printf '\ndeveloper_instructions = "%s"\n' "$PLANNOTATOR_INSTRUCTION" >> "$CODEX_CONFIG"
        echo -e "${GREEN}✓ Added developer_instructions to ${CODEX_CONFIG}${NC}"
      fi
    fi
  fi
fi
echo ""

# ════════════════════════════════════════════════════════════
# PART 2: plannotator prompt file
# ════════════════════════════════════════════════════════════
echo -e "${BLUE}━━ Step 2: plannotator prompt file ━━━━━━━━━━━━━━━${NC}"
echo ""

PROMPT_CONTENT='# plannotator — Plan Review Agent

Use this prompt to do a plan review session with plannotator before implementation.

## How to Use

```bash
# In Codex, invoke with:
/prompts:plannotator "Review my plan for [feature]"
```

## Workflow

1. Create your implementation plan in markdown format
2. Pipe it to plannotator for human review:
   ```bash
   cat > /tmp/plan.md << '"'"'PLAN
   # Implementation Plan: [Feature Name]

   ## Steps
   1. ...
   2. ...
   PLAN

   python3 -c "import json; print(json.dumps({\"tool_input\": {\"plan\": open(\"/tmp/plan.md\").read(), \"permission_mode\": \"acceptEdits\"}}))" | plannotator > /tmp/plannotator_feedback.txt 2>&1 &
   ```
3. User reviews and annotates in browser UI
4. If approved → proceed with implementation
5. If changes requested → revise plan and resubmit

## After Coding

```bash
# Review all uncommitted changes
plannotator review

# Review a specific commit
plannotator review HEAD~1

# Review branch diff
plannotator review main...HEAD
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `PLANNOTATOR_REMOTE` | Set to `1` for remote/SSH mode |
| `PLANNOTATOR_PORT` | Fixed port (default: random) |
| `PLANNOTATOR_BROWSER` | Custom browser path |

## Obsidian Integration

Approved plans auto-save to Obsidian when enabled in plannotator UI settings.
Install Obsidian: https://obsidian.md/download
'

if [ -f "$PLANNOTATOR_PROMPT" ]; then
  echo -e "${YELLOW}⚠ ${PLANNOTATOR_PROMPT} already exists${NC}"
  echo -e "${GRAY}  Skipping (delete file to recreate).${NC}"
elif [ "$DRY_RUN" = true ]; then
  echo -e "${YELLOW}[DRY RUN] Would create ${PLANNOTATOR_PROMPT}${NC}"
else
  printf '%s\n' "$PROMPT_CONTENT" > "$PLANNOTATOR_PROMPT"
  echo -e "${GREEN}✓ Created ${PLANNOTATOR_PROMPT}${NC}"
fi
echo ""

echo -e "${GREEN}Codex CLI setup complete!${NC}"
echo ""
echo -e "${BLUE}How to use plannotator in Codex:${NC}"
echo ""
echo -e "  ${BLUE}Plan review:${NC}"
echo -e "    ${GREEN}cat > /tmp/plan.md << 'PLAN'${NC}"
echo -e "    ${GREEN}# ...your markdown...${NC}"
echo -e "    ${GREEN}PLAN${NC}"
echo -e "    ${GREEN}python3 -c \"import json; print(json.dumps({\\\"tool_input\\\": {\\\"plan\\\": open(\\\"/tmp/plan.md\\\").read(), \\\"permission_mode\\\": \\\"acceptEdits\\\"}}))\" | plannotator > /tmp/plannotator_feedback.txt 2>&1 &${NC}"
echo ""
echo -e "  ${BLUE}Code review after coding:${NC}"
echo -e "    ${GREEN}plannotator review${NC}"
echo ""
echo -e "  ${BLUE}Use plannotator agent prompt:${NC}"
echo -e "    ${GREEN}/prompts:plannotator${NC}  (inside Codex interactive session)"
echo ""
echo -e "${BLUE}Next steps:${NC}"
echo -e "  ${BLUE}1.${NC} Run ${GREEN}./check-status.sh${NC} to verify configuration"
echo -e "  ${BLUE}2.${NC} Start a Codex session and use plannotator review"
echo ""

#!/bin/bash
# plannotator - Gemini CLI Hook Setup Script
# Adds the ExitPlanMode hook to ~/.gemini/settings.json
# and plannotator instructions to ~/.gemini/GEMINI.md
#
# Usage: ./setup-gemini-hook.sh [--dry-run] [--md-only] [--hook-only]

set -e

RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
GRAY='\033[0;37m'
NC='\033[0m'

DRY_RUN=false
MD_ONLY=false
HOOK_ONLY=false

for arg in "$@"; do
  case $arg in
    --dry-run)  DRY_RUN=true ;;
    --md-only)  MD_ONLY=true ;;
    --hook-only) HOOK_ONLY=true ;;
    -h|--help)
      echo "Usage: $0 [--dry-run] [--md-only] [--hook-only]"
      echo ""
      echo "Configures plannotator for Gemini CLI:"
      echo "  1. Adds ExitPlanMode hook to ~/.gemini/settings.json"
      echo "  2. Adds plannotator instructions to ~/.gemini/GEMINI.md"
      echo ""
      echo "Options:"
      echo "  --dry-run    Show what would change without writing"
      echo "  --md-only    Only update GEMINI.md (skip settings.json hook)"
      echo "  --hook-only  Only update settings.json (skip GEMINI.md)"
      echo "  -h, --help   Show this help"
      exit 0
      ;;
  esac
done

GEMINI_DIR="$HOME/.gemini"
SETTINGS_FILE="$GEMINI_DIR/settings.json"
GEMINI_MD="$GEMINI_DIR/GEMINI.md"

echo ""
echo -e "${BLUE}╔════════════════════════════════════════════╗${NC}"
echo -e "${BLUE}║  plannotator × Gemini CLI Setup            ║${NC}"
echo -e "${BLUE}╚════════════════════════════════════════════╝${NC}"
echo ""

# ── Check plannotator CLI ─────────────────────────────────
if ! command -v plannotator &>/dev/null; then
  echo -e "${RED}✗ plannotator CLI not found${NC}"
  echo -e "${YELLOW}  Run ./install.sh first${NC}"
  exit 1
fi
echo -e "${GREEN}✓ plannotator CLI is installed${NC}"
echo ""

# ── Check Gemini CLI ──────────────────────────────────────
if ! command -v gemini &>/dev/null; then
  echo -e "${YELLOW}⚠ gemini CLI not found in PATH${NC}"
  echo -e "${GRAY}  Install via: npm install -g @google/gemini-cli${NC}"
  echo -e "${GRAY}  Continuing setup anyway (settings will be ready when gemini is installed)${NC}"
  echo ""
fi

mkdir -p "$GEMINI_DIR"

# ════════════════════════════════════════════════════════════
# PART 1: Hook in ~/.gemini/settings.json
# ════════════════════════════════════════════════════════════
if [ "$MD_ONLY" = false ]; then
  echo -e "${BLUE}━━ Step 1: settings.json hook ━━━━━━━━━━━━━━━━━━${NC}"
  echo ""

  if [ -f "$SETTINGS_FILE" ] && grep -q "plannotator" "$SETTINGS_FILE" 2>/dev/null; then
    echo -e "${YELLOW}⚠ plannotator hook already in ${SETTINGS_FILE}${NC}"
    echo -e "${GRAY}  No changes made.${NC}"
  else
    # Hook JSON (Gemini CLI uses same format as Claude Code)
    HOOK_BLOCK='{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "plannotator",
            "timeout": 1800
          }
        ]
      }
    ]
  }
}'

    echo -e "${BLUE}Hook to be added to ${SETTINGS_FILE}:${NC}"
    echo "$HOOK_BLOCK"
    echo ""

    if [ "$DRY_RUN" = true ]; then
      echo -e "${YELLOW}[DRY RUN] No changes written to settings.json${NC}"
    elif [ ! -f "$SETTINGS_FILE" ]; then
      # Create new settings.json
      cat > "$SETTINGS_FILE" <<'EOF'
{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "plannotator",
            "timeout": 1800
          }
        ]
      }
    ]
  }
}
EOF
      echo -e "${GREEN}✓ Created ${SETTINGS_FILE} with plannotator hook${NC}"
    else
      # Merge into existing settings.json
      BACKUP="${SETTINGS_FILE}.bak.$(date +%Y%m%d%H%M%S)"
      cp "$SETTINGS_FILE" "$BACKUP"
      echo -e "${GRAY}  Backup saved: ${BACKUP}${NC}"

      if command -v python3 &>/dev/null; then
        python3 - "$SETTINGS_FILE" <<'PYEOF'
import json, sys

path = sys.argv[1]
with open(path) as f:
    settings = json.load(f)

new_hook = {
    "matcher": "ExitPlanMode",
    "hooks": [{"type": "command", "command": "plannotator", "timeout": 1800}]
}

hooks = settings.setdefault("hooks", {})
perm = hooks.setdefault("PermissionRequest", [])

for h in perm:
    if h.get("matcher") == "ExitPlanMode" and any(
        x.get("command") == "plannotator" for x in h.get("hooks", [])
    ):
        print("Hook already present — no changes made.")
        sys.exit(0)

perm.append(new_hook)

with open(path, "w") as f:
    json.dump(settings, f, indent=2)
    f.write("\n")

print("Hook merged successfully.")
PYEOF
        echo -e "${GREEN}✓ Hook merged into ${SETTINGS_FILE}${NC}"
      else
        echo -e "${RED}✗ python3 not found — cannot merge JSON safely${NC}"
        echo -e "${YELLOW}  Add manually to ${SETTINGS_FILE}:${NC}"
        echo "$HOOK_BLOCK"
        exit 1
      fi
    fi
  fi

  # Also try Gemini CLI's built-in hook migration if available
  if command -v gemini &>/dev/null && gemini hooks --help 2>/dev/null | grep -q migrate; then
    echo ""
    echo -e "${GRAY}  Tip: You can also run 'gemini hooks migrate --from-claude' to auto-migrate Claude Code hooks.${NC}"
  fi
  echo ""
fi

# ════════════════════════════════════════════════════════════
# PART 2: GEMINI.md instructions
# ════════════════════════════════════════════════════════════
if [ "$HOOK_ONLY" = false ]; then
  echo -e "${BLUE}━━ Step 2: GEMINI.md plannotator instructions ━━━━${NC}"
  echo ""

  PLANNOTATOR_MD_BLOCK='
## plannotator — Plan Review

When you have a complete implementation plan, **always submit it for human review** before proceeding:

```bash
# Save markdown plan to file, then send validated JSON payload:
cat > /tmp/plan.md << 'PLAN'
# Your plan markdown...
PLAN

python3 -c "
import json
print(json.dumps({'tool_input': {'plan': open('/tmp/plan.md').read(), 'permission_mode': 'acceptEdits'}}))
" | plannotator > /tmp/plannotator_feedback.txt 2>&1 &
```

**Workflow:**
1. Create your implementation plan in markdown
2. Run the python3 JSON command above (manual mode) OR let ExitPlanMode hook trigger automatically
3. Wait for user approval in the browser UI
4. If approved → proceed with implementation
5. If changes requested → revise and resubmit

**Code review after implementation:**
```bash
plannotator review          # Review all uncommitted changes
plannotator review HEAD~1   # Review specific commit
```

**Plan mode:** Run `gemini --approval-mode plan` to work in read-only planning mode.
plannotator hooks automatically trigger when you exit plan mode.
'

  if [ -f "$GEMINI_MD" ] && grep -q "plannotator" "$GEMINI_MD" 2>/dev/null; then
    echo -e "${YELLOW}⚠ plannotator instructions already in ${GEMINI_MD}${NC}"
    echo -e "${GRAY}  No changes made.${NC}"
  else
    if [ "$DRY_RUN" = true ]; then
      echo -e "${YELLOW}[DRY RUN] Would append to ${GEMINI_MD}:${NC}"
      echo "$PLANNOTATOR_MD_BLOCK"
    else
      # Append plannotator section to GEMINI.md
      if [ ! -f "$GEMINI_MD" ]; then
        cat > "$GEMINI_MD" <<EOF
# Gemini CLI Agent Configuration
EOF
      fi
      printf "\n%s\n" "$PLANNOTATOR_MD_BLOCK" >> "$GEMINI_MD"
      echo -e "${GREEN}✓ plannotator instructions added to ${GEMINI_MD}${NC}"
    fi
  fi
  echo ""
fi

# ════════════════════════════════════════════════════════════
# Summary
# ════════════════════════════════════════════════════════════
echo -e "${GREEN}Gemini CLI setup complete!${NC}"
echo ""
echo -e "${BLUE}How it works:${NC}"
echo -e "  When Gemini exits plan mode (--approval-mode plan),"
echo -e "  plannotator opens automatically in your browser."
echo ""
echo -e "${BLUE}Manual trigger:${NC}"
echo -e "  ${GREEN}cat > /tmp/plan.md << 'PLAN'${NC}"
echo -e "  ${GREEN}# ...your markdown...${NC}"
echo -e "  ${GREEN}PLAN${NC}"
echo -e "  ${GREEN}python3 -c \"import json; print(json.dumps({'tool_input': {'plan': open('/tmp/plan.md').read(), 'permission_mode': 'acceptEdits'}}))\" | plannotator > /tmp/plannotator_feedback.txt 2>&1 &${NC}"
echo -e "  ${GREEN}plannotator review${NC}   (review git diff)"
echo ""
echo -e "${BLUE}Next steps:${NC}"
echo -e "  ${BLUE}1.${NC} Run ${GREEN}./check-status.sh${NC} to verify configuration"
echo -e "  ${BLUE}2.${NC} Use ${GREEN}gemini --approval-mode plan${NC} to enable plan review"
echo ""

#!/bin/bash
# plannotator - Claude Code Hook Setup Script
# Adds the ExitPlanMode hook to ~/.claude/settings.json
# Use this as an alternative to the Claude Code plugin install.
#
# Usage: ./setup-hook.sh [--dry-run]

set -e

RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
GRAY='\033[0;37m'
NC='\033[0m'

DRY_RUN=false
for arg in "$@"; do
  case $arg in
    --dry-run) DRY_RUN=true ;;
    -h|--help)
      echo "Usage: $0 [--dry-run]"
      echo ""
      echo "Adds the plannotator hook to ~/.claude/settings.json"
      echo ""
      echo "Options:"
      echo "  --dry-run   Show what would be changed without writing"
      echo "  -h, --help  Show this help"
      exit 0
      ;;
  esac
done

SETTINGS_FILE="$HOME/.claude/settings.json"
SETTINGS_DIR="$HOME/.claude"

echo ""
echo -e "${BLUE}╔════════════════════════════════════════════╗${NC}"
echo -e "${BLUE}║    plannotator Hook Setup                  ║${NC}"
echo -e "${BLUE}╚════════════════════════════════════════════╝${NC}"
echo ""

# Check plannotator is installed
if ! command -v plannotator &>/dev/null; then
  echo -e "${RED}✗ plannotator CLI not found${NC}"
  echo -e "${YELLOW}  Run ./install.sh first${NC}"
  exit 1
fi

echo -e "${GREEN}✓ plannotator CLI is installed${NC}"
echo ""

# Check if already configured
if [ -f "$SETTINGS_FILE" ] && grep -q "plannotator" "$SETTINGS_FILE" 2>/dev/null; then
  echo -e "${YELLOW}⚠ plannotator hook already exists in ${SETTINGS_FILE}${NC}"
  echo ""
  echo -e "Current hook configuration:"
  grep -A3 -B1 "plannotator" "$SETTINGS_FILE" 2>/dev/null | head -20
  echo ""
  echo -e "${GRAY}No changes made. Remove manually if you want to reconfigure.${NC}"
  exit 0
fi

# The hook JSON to inject
HOOK_JSON='{
  "PermissionRequest": [
    {
      "matcher": "ExitPlanMode",
      "hooks": [
        {
          "type": "command",
          "command": "plannotator",
          "timeout": 1800
        }
      ]
    }
  ]
}'

echo -e "${BLUE}Hook to be added:${NC}"
echo "$HOOK_JSON"
echo ""

if [ "$DRY_RUN" = true ]; then
  echo -e "${YELLOW}[DRY RUN] No changes written.${NC}"
  echo -e "Target file: ${SETTINGS_FILE}"
  exit 0
fi

# Ensure ~/.claude directory exists
mkdir -p "$SETTINGS_DIR"

if [ ! -f "$SETTINGS_FILE" ]; then
  # Create new settings.json with hook
  echo -e "${BLUE}Creating new settings file: ${SETTINGS_FILE}${NC}"
  cat > "$SETTINGS_FILE" <<EOF
{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "plannotator",
            "timeout": 1800
          }
        ]
      }
    ]
  }
}
EOF
  echo -e "${GREEN}✓ Created ${SETTINGS_FILE} with plannotator hook${NC}"

else
  # Merge into existing settings.json
  echo -e "${BLUE}Merging hook into existing: ${SETTINGS_FILE}${NC}"
  echo ""

  # Back up existing settings
  BACKUP="${SETTINGS_FILE}.bak.$(date +%Y%m%d%H%M%S)"
  cp "$SETTINGS_FILE" "$BACKUP"
  echo -e "${GRAY}  Backup saved: ${BACKUP}${NC}"

  # Use Python (available on macOS/Linux) to merge JSON safely
  if command -v python3 &>/dev/null; then
    python3 - "$SETTINGS_FILE" <<'PYEOF'
import json, sys

path = sys.argv[1]
with open(path) as f:
    settings = json.load(f)

new_hook = {
    "matcher": "ExitPlanMode",
    "hooks": [{"type": "command", "command": "plannotator", "timeout": 1800}]
}

hooks = settings.setdefault("hooks", {})
perm = hooks.setdefault("PermissionRequest", [])

# Don't add if already present
for h in perm:
    if h.get("matcher") == "ExitPlanMode" and any(
        x.get("command") == "plannotator" for x in h.get("hooks", [])
    ):
        print("Hook already present — no changes made.")
        sys.exit(0)

perm.append(new_hook)

with open(path, "w") as f:
    json.dump(settings, f, indent=2)
    f.write("\n")

print("Hook merged successfully.")
PYEOF

    echo -e "${GREEN}✓ Hook added to ${SETTINGS_FILE}${NC}"

  else
    echo -e "${RED}✗ python3 not found — cannot merge JSON safely${NC}"
    echo -e "${YELLOW}  Add this manually to ${SETTINGS_FILE}:${NC}"
    echo ""
    echo '  "hooks": {'
    echo '    "PermissionRequest": ['
    echo '      {'
    echo '        "matcher": "ExitPlanMode",'
    echo '        "hooks": [{"type": "command", "command": "plannotator", "timeout": 1800}]'
    echo '      }'
    echo '    ]'
    echo '  }'
    exit 1
  fi
fi

echo ""
echo -e "${GREEN}Hook setup complete!${NC}"
echo ""
echo -e "${BLUE}How it works:${NC}"
echo -e "  When Claude Code finishes planning (Shift+Tab×2 in plan mode),"
echo -e "  plannotator opens automatically in your browser."
echo ""
echo -e "${BLUE}Next steps:${NC}"
echo -e "  ${BLUE}1.${NC} Restart Claude Code for hooks to take effect"
echo -e "  ${BLUE}2.${NC} Run ${GREEN}./check-status.sh${NC} to verify configuration"
echo ""

#!/bin/bash
# plannotator - OpenCode Plugin Registration Script
# Registers @plannotator/opencode@latest plugin in opencode.json
# and copies slash commands to ~/.config/opencode/command/
#
# Usage: ./setup-opencode-plugin.sh [--dry-run] [--project-dir DIR]

set -e

RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
GRAY='\033[0;37m'
NC='\033[0m'

DRY_RUN=false
PROJECT_DIR="${PWD}"

for arg in "$@"; do
  case $arg in
    --dry-run) DRY_RUN=true ;;
    --project-dir=*) PROJECT_DIR="${arg#*=}" ;;
    --project-dir)   PROJECT_DIR="" ;;
    -h|--help)
      echo "Usage: $0 [--dry-run] [--project-dir DIR]"
      echo ""
      echo "Registers plannotator OpenCode plugin:"
      echo "  1. Adds @plannotator/opencode@latest to opencode.json"
      echo "  2. Copies slash commands to ~/.config/opencode/command/"
      echo ""
      echo "Options:"
      echo "  --project-dir DIR  Target project dir (default: current dir)"
      echo "  --dry-run          Show what would change without writing"
      echo "  -h, --help         Show this help"
      exit 0
      ;;
  esac
done

OPENCODE_JSON="${PROJECT_DIR}/opencode.json"
OPENCODE_COMMAND_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/opencode/command"
PLUGIN_NAME="@plannotator/opencode@latest"

echo ""
echo -e "${BLUE}╔════════════════════════════════════════════╗${NC}"
echo -e "${BLUE}║  plannotator × OpenCode Plugin Setup       ║${NC}"
echo -e "${BLUE}╚════════════════════════════════════════════╝${NC}"
echo ""
echo -e "${GRAY}Project dir: ${PROJECT_DIR}${NC}"
echo ""

if ! command -v plannotator &>/dev/null; then
  echo -e "${RED}✗ plannotator CLI not found${NC}"
  echo -e "${YELLOW}  Run ./install.sh first${NC}"
  exit 1
fi
echo -e "${GREEN}✓ plannotator CLI is installed${NC}"
echo ""

# ════════════════════════════════════════════════════════════
# PART 1: opencode.json plugin registration
# ════════════════════════════════════════════════════════════
echo -e "${BLUE}━━ Step 1: opencode.json plugin registration ━━━━━${NC}"
echo ""

if [ -f "$OPENCODE_JSON" ] && grep -q "plannotator" "$OPENCODE_JSON" 2>/dev/null; then
  echo -e "${YELLOW}⚠ plannotator already in ${OPENCODE_JSON}${NC}"
  echo -e "${GRAY}  No changes needed.${NC}"
elif [ "$DRY_RUN" = true ]; then
  echo -e "${YELLOW}[DRY RUN] Would add '${PLUGIN_NAME}' to ${OPENCODE_JSON}${NC}"
else
  if [ ! -f "$OPENCODE_JSON" ]; then
    cat > "$OPENCODE_JSON" <<EOF
{
  "\$schema": "https://opencode.ai/config.json",
  "plugin": ["${PLUGIN_NAME}"]
}
EOF
    echo -e "${GREEN}✓ Created ${OPENCODE_JSON} with plannotator plugin${NC}"
  else
    BACKUP="${OPENCODE_JSON}.bak.$(date +%Y%m%d%H%M%S)"
    cp "$OPENCODE_JSON" "$BACKUP"
    echo -e "${GRAY}  Backup saved: ${BACKUP}${NC}"

    if command -v python3 &>/dev/null; then
      python3 - "$OPENCODE_JSON" "$PLUGIN_NAME" <<'PYEOF'
import json, sys

path = sys.argv[1]
plugin = sys.argv[2]

with open(path) as f:
    config = json.load(f)

plugins = config.setdefault("plugin", [])

if any("plannotator" in p for p in plugins):
    print("plannotator plugin already present — no change.")
    sys.exit(0)

plugins.append(plugin)

with open(path, "w") as f:
    json.dump(config, f, indent=2)
    f.write("\n")

print("Plugin registered.")
PYEOF
      echo -e "${GREEN}✓ Added plannotator plugin to ${OPENCODE_JSON}${NC}"
    else
      echo -e "${RED}✗ python3 not found — add manually to ${OPENCODE_JSON}:${NC}"
      echo '  "plugin": ["'"${PLUGIN_NAME}"'"]'
      exit 1
    fi
  fi
fi
echo ""

# ════════════════════════════════════════════════════════════
# PART 2: Slash commands for OpenCode
# ════════════════════════════════════════════════════════════
echo -e "${BLUE}━━ Step 2: OpenCode slash commands ━━━━━━━━━━━━━━━${NC}"
echo ""

REVIEW_CMD="${OPENCODE_COMMAND_DIR}/plannotator-review.md"
ANNOTATE_CMD="${OPENCODE_COMMAND_DIR}/plannotator-annotate.md"

REVIEW_CMD_CONTENT='---
description: Open interactive code review for current changes
---

Open the plannotator code review UI for current git diff.

!`plannotator review`

Address the code review feedback above.'

ANNOTATE_CMD_CONTENT='---
description: Open interactive annotation UI for a markdown file
---

!`plannotator annotate "$ARGUMENTS"`

Address the annotation feedback above.'

if [ "$DRY_RUN" = true ]; then
  echo -e "${YELLOW}[DRY RUN] Would create:${NC}"
  echo -e "  ${REVIEW_CMD}"
  echo -e "  ${ANNOTATE_CMD}"
else
  mkdir -p "$OPENCODE_COMMAND_DIR"

  if [ ! -f "$REVIEW_CMD" ]; then
    printf '%s\n' "$REVIEW_CMD_CONTENT" > "$REVIEW_CMD"
    echo -e "${GREEN}✓ Created /plannotator-review command${NC}"
  else
    echo -e "${GRAY}  /plannotator-review already exists — skipped${NC}"
  fi

  if [ ! -f "$ANNOTATE_CMD" ]; then
    printf '%s\n' "$ANNOTATE_CMD_CONTENT" > "$ANNOTATE_CMD"
    echo -e "${GREEN}✓ Created /plannotator-annotate command${NC}"
  else
    echo -e "${GRAY}  /plannotator-annotate already exists — skipped${NC}"
  fi
fi
echo ""

echo -e "${GREEN}OpenCode plugin setup complete!${NC}"
echo ""
echo -e "${BLUE}Next steps:${NC}"
echo -e "  ${BLUE}1.${NC} ${YELLOW}Restart OpenCode${NC} for the plugin to take effect"
echo -e "  ${BLUE}2.${NC} Add to ${GREEN}opencode.json${NC} if not auto-detected:"
echo ""
echo -e '    {  "'
echo -e '      "$schema": "https://opencode.ai/config.json",'
echo -e "      \"plugin\": [\"${PLUGIN_NAME}\"]"
echo -e '    }'
echo ""
echo -e "  ${BLUE}3.${NC} Available slash commands after restart:"
echo -e "    ${GREEN}/plannotator-review${NC}         — code review"
echo -e "    ${GREEN}/plannotator-annotate file.md${NC} — annotate markdown"
echo ""
echo -e "  ${BLUE}4.${NC} The ${GREEN}submit_plan${NC} tool is automatically available to the agent"
echo ""

{
  "schema_version": "2.0",
  "meta": {
    "generated_at": "2026-03-22T08:15:00.086Z",
    "slug": "supercent-io-plannotator",
    "source_url": "https://github.com/supercent-io/skills-template/tree/main/.agent-skills/plannotator/",
    "source_ref": "main",
    "model": "claude",
    "analysis_version": "3.0.0",
    "source_type": "community",
    "content_hash": "6b04c43272726a909eea0e0a7451ac919571df02818f501489010834280b15e8",
    "tree_hash": "66dfb9c2dcb6c730b3e902f7ceb86c5e5e81c62f6c6d06ae198d8f7f317ab087"
  },
  "skill": {
    "name": "plannotator",
    "description": "Interactive plan and diff review for AI coding agents with visual browser UI for annotating plans, approving or requesting changes with structured feedback, and auto-save to Obsidian or Bear Notes.",
    "summary": "Visual plan review and code annotation tool for Claude Code, Codex, Gemini CLI, and OpenCode with structured feedback loops.",
    "icon": "📦",
    "version": "0.9.2",
    "author": "supercent-io",
    "license": "MIT",
    "category": "productivity",
    "tags": [
      "plan-review",
      "code-review",
      "Claude Code",
      "Codex",
      "annotation"
    ],
    "supported_tools": [
      "claude",
      "codex",
      "claude-code"
    ],
    "risk_factors": [
      "scripts",
      "network",
      "filesystem",
      "external_commands"
    ]
  },
  "security_audit": {
    "risk_level": "low",
    "is_blocked": false,
    "safe_to_publish": true,
    "summary": "Legitimate plan review tool for AI coding agents. Static analysis flagged 380 patterns across 10 files, but most are false positives for standard installer/hook functionality. The curl | bash installation pattern presents supply chain risk but is common practice. All filesystem access targets standard AI tool config locations. No credential exfiltration or command injection vectors detected.",
    "risk_factor_evidence": [
      {
        "factor": "external_commands",
        "evidence": [
          {
            "file": "scripts/install.sh",
            "line_start": 105,
            "line_end": 105
          },
          {
            "file": "scripts/install.sh",
            "line_start": 110,
            "line_end": 110
          },
          {
            "file": "scripts/setup-hook.sh",
            "line_start": 71,
            "line_end": 73
          }
        ]
      },
      {
        "factor": "network",
        "evidence": [
          {
            "file": "scripts/install.sh",
            "line_start": 105,
            "line_end": 105
          },
          {
            "file": "SKILL.md",
            "line_start": 73,
            "line_end": 73
          }
        ]
      },
      {
        "factor": "filesystem",
        "evidence": [
          {
            "file": "scripts/setup-hook.sh",
            "line_start": 34,
            "line_end": 35
          },
          {
            "file": "scripts/setup-gemini-hook.sh",
            "line_start": 30,
            "line_end": 31
          },
          {
            "file": "scripts/setup-codex-hook.sh",
            "line_start": 37,
            "line_end": 40
          }
        ]
      }
    ],
    "critical_findings": [],
    "high_findings": [],
    "medium_findings": [
      {
        "title": "Pipe to Shell Installation Pattern",
        "description": "The install.sh script uses curl | bash pattern to download and execute remote scripts. This presents supply chain risk if the remote server is compromised. Commands are executed from plannotator.ai/install.sh without integrity verification.",
        "locations": [
          {
            "file": "scripts/install.sh",
            "line_start": 105,
            "line_end": 105
          },
          {
            "file": "scripts/install.sh",
            "line_start": 110,
            "line_end": 110
          }
        ],
        "confidence": 0.95,
        "confidence_reasoning": "Direct evidence of curl piped to bash without hash verification - classic supply chain attack vector, though commonly used for convenience."
      }
    ],
    "low_findings": [
      {
        "title": "AI Tool Configuration File Modification",
        "description": "Scripts modify configuration files for Claude Code, Gemini CLI, and Codex CLI. This is intended functionality but grants persistent access to AI tool behavior.",
        "locations": [
          {
            "file": "scripts/setup-hook.sh",
            "line_start": 34,
            "line_end": 35
          },
          {
            "file": "scripts/setup-gemini-hook.sh",
            "line_start": 30,
            "line_end": 31
          },
          {
            "file": "scripts/setup-codex-hook.sh",
            "line_start": 37,
            "line_end": 40
          }
        ],
        "confidence": 0.9,
        "confidence_reasoning": "Files explicitly target AI tool config locations with hardcoded JSON paths - legitimate hook setup but persistent modification of AI behavior."
      },
      {
        "title": "Remote Shell Configuration",
        "description": "configure-remote.sh modifies shell profile files (.zshrc, .bashrc) and SSH configuration for remote mode. This is intended for devcontainer/WSL support but modifies persistent shell environment.",
        "locations": [
          {
            "file": "scripts/configure-remote.sh",
            "line_start": 130,
            "line_end": 130
          }
        ],
        "confidence": 0.85,
        "confidence_reasoning": "Script modifies shell profiles for remote development support - legitimate use case but persistent environment modification warrants user awareness."
      }
    ],
    "dangerous_patterns": [
      {
        "title": "Remote Script Execution",
        "description": "Installation downloads and executes scripts from remote server without integrity checks. Users should verify the source before running.",
        "locations": [
          {
            "file": "scripts/install.sh",
            "line_start": 105,
            "line_end": 105
          }
        ]
      }
    ],
    "files_scanned": 10,
    "total_lines": 2251,
    "audit_model": "claude",
    "audited_at": "2026-03-22T08:15:00.086Z"
  },
  "content": {
    "user_title": "Review AI Agent Plans Visually Before Coding",
    "value_statement": "Catch implementation mistakes before code is written by reviewing AI agent plans in a visual browser interface. Annotate plans with structured feedback, approve or request changes, and auto-save to Obsidian or Bear Notes.",
    "seo_keywords": [
      "Claude Code plan review",
      "Codex CLI annotations",
      "AI agent feedback",
      "plan approval workflow",
      "Claude Code hook",
      "code review tool",
      "Obsidian integration",
      "AI coding assistant"
    ],
    "actual_capabilities": [
      "Opens visual browser UI when AI agents exit plan mode for interactive plan review",
      "Annotates plans with delete, insert, replace, and comment markers for structured feedback",
      "Reviews git diffs after implementation with unified or split view comparison",
      "Auto-saves approved plans to Obsidian vaults with YAML frontmatter and tags",
      "Integrates with Claude Code, Gemini CLI, Codex CLI, and OpenCode via hooks or plugins",
      "Supports remote development via SSH port forwarding and devcontainer mode"
    ],
    "limitations": [
      "Requires browser access for visual UI - headless or automated browser sessions cannot configure settings",
      "Export and Notes save features only work in hook mode, not in standalone CLI review mode",
      "Bear Notes integration requires macOS or iOS - not available on Linux or Windows",
      "Settings persist in browser cookies, not localStorage - different browser profiles do not share configuration"
    ],
    "use_cases": [
      {
        "title": "Pre-Implementation Plan Review",
        "description": "Review AI agent implementation plans before any code is written. Annotate risky steps, add missing requirements, and approve only when the approach aligns with project goals.",
        "target_user": "Engineering leads managing AI-assisted development teams"
      },
      {
        "title": "Post-Implementation Code Review",
        "description": "Review git diffs after AI agents complete coding. Annotate specific line ranges with expected behavior changes and attach screenshots for UI feedback.",
        "target_user": "Developers using Claude Code or Codex for rapid prototyping"
      },
      {
        "title": "Team Knowledge Sharing",
        "description": "Share annotated plan reviews with teammates via link. Auto-save approved plans to Obsidian for team documentation and future reference.",
        "target_user": "Technical architects documenting system design decisions"
      }
    ],
    "prompt_templates": [
      {
        "title": "Basic Plan Review",
        "prompt": "Review this implementation plan and annotate any steps that seem risky or incomplete. Mark steps to delete, insert, or replace with specific feedback.",
        "scenario": "First-time user reviewing a simple feature plan"
      },
      {
        "title": "Architecture Review Request",
        "prompt": "Review this plan focusing on architectural implications. Check for: database schema changes, API contract modifications, backward compatibility, and migration requirements. Add comments for any missing considerations.",
        "scenario": "Senior developer reviewing a complex refactor plan"
      },
      {
        "title": "Security Review Checklist",
        "prompt": "Review this plan for security concerns. Verify: input validation, authentication checks, authorization boundaries, data sanitization, and logging requirements. Request changes for any security gaps.",
        "scenario": "Security-conscious review of authentication feature"
      },
      {
        "title": "Team Review Workflow",
        "prompt": "Create a plan review session that can be shared with the team. Include: project context, acceptance criteria, performance requirements, and testing strategy. Enable Obsidian auto-save for documentation.",
        "scenario": "Tech lead preparing a plan for team alignment"
      }
    ],
    "output_examples": [
      {
        "input": "AI agent submits a plan to add user authentication with JWT tokens",
        "output": [
          "Plan opened in browser UI at localhost:19432",
          "Reviewer annotates step 3: 'Replace - Add rate limiting to login endpoint'",
          "Reviewer adds comment: 'Include password complexity requirements'",
          "Reviewer clicks Approve - agent proceeds with implementation"
        ]
      },
      {
        "input": "Developer runs plannotator review after agent completes coding",
        "output": [
          "Git diff loaded with 5 file changes",
          "Line 42-48 annotated: 'This validation should happen before database write'",
          "Image attached showing expected UI layout",
          "Feedback exported to markdown for agent reference"
        ]
      }
    ],
    "best_practices": [
      "Review plans before implementation starts to catch wrong approaches early and save iteration time",
      "Keep each annotation tied to one concrete actionable change for clarity",
      "Include acceptance criteria when requesting changes so the agent knows what success looks like"
    ],
    "anti_patterns": [
      "Approving plans without reading - defeats the purpose of catching mistakes before coding",
      "Vague annotations like 'fix this' without explaining what change is needed",
      "Requesting major scope changes after approval - create a new plan review instead"
    ],
    "faq": [
      {
        "question": "How do I install plannotator for Claude Code?",
        "answer": "Run ./install.sh --with-plugin for CLI and plugin commands, then run /plugin marketplace add backnotprop/plannotator inside Claude Code. Alternatively run ./setup-hook.sh for manual hook configuration. Restart Claude Code after setup."
      },
      {
        "question": "Does plannotator work with Gemini CLI and Codex CLI?",
        "answer": "Yes. Run ./setup-gemini-hook.sh for Gemini CLI or ./setup-codex-hook.sh for Codex CLI. You can also run ./install.sh --all to configure all AI tool integrations at once."
      },
      {
        "question": "How does the Obsidian auto-save feature work?",
        "answer": "Enable Obsidian integration in Settings gear icon then Saving tab. Select your vault from the dropdown. Approved plans auto-save with YAML frontmatter including tags for project name, title words, and detected languages."
      },
      {
        "question": "Can I use plannotator on a remote server or devcontainer?",
        "answer": "Yes. Run ./configure-remote.sh to set up SSH port forwarding. Set PLANNOTATOR_REMOTE=1 to disable auto-browser-open and PLANNOTATOR_PORT to use a fixed port. Forward the port via SSH and access via browser."
      },
      {
        "question": "What happens if I deny a plan?",
        "answer": "Your annotations are sent back as structured feedback to the AI agent. The agent can then revise the plan based on your comments and resubmit for another review cycle."
      },
      {
        "question": "Do I need Obsidian to use plannotator?",
        "answer": "No. Obsidian integration is optional. You can review and approve plans without it. Auto-save can be enabled later via the Settings UI if you install Obsidian."
      }
    ]
  },
  "file_structure": [
    {
      "name": "scripts",
      "type": "dir",
      "path": "scripts",
      "children": [
        {
          "name": "check-status.sh",
          "type": "file",
          "path": "scripts/check-status.sh",
          "lines": 279
        },
        {
          "name": "configure-remote.sh",
          "type": "file",
          "path": "scripts/configure-remote.sh",
          "lines": 189
        },
        {
          "name": "install.sh",
          "type": "file",
          "path": "scripts/install.sh",
          "lines": 215
        },
        {
          "name": "review.sh",
          "type": "file",
          "path": "scripts/review.sh",
          "lines": 93
        },
        {
          "name": "setup-codex-hook.sh",
          "type": "file",
          "path": "scripts/setup-codex-hook.sh",
          "lines": 227
        },
        {
          "name": "setup-gemini-hook.sh",
          "type": "file",
          "path": "scripts/setup-gemini-hook.sh",
          "lines": 265
        },
        {
          "name": "setup-hook.sh",
          "type": "file",
          "path": "scripts/setup-hook.sh",
          "lines": 189
        },
        {
          "name": "setup-opencode-plugin.sh",
          "type": "file",
          "path": "scripts/setup-opencode-plugin.sh",
          "lines": 187
        }
      ]
    },
    {
      "name": "SKILL.md",
      "type": "file",
      "path": "SKILL.md",
      "lines": 577
    },
    {
      "name": "SKILL.toon",
      "type": "file",
      "path": "SKILL.toon",
      "lines": 30
    }
  ]
}