fix: v2.36.2 sync canonical skill scripts to top-level (PR #149 by @voidborne-d)

Closes the v2.36.0 regression where slug-mode init-session.sh shipped only in
scripts/ and never reached skills/planning-with-files/scripts/ or the nine IDE
mirror folders. Users installing via npx skills or any IDE folder silently
received the v2.0.0 legacy-only script.

Also synced:
- analytics template support in init-session.ps1 (missed since v2.29.0)
- /usr/bin/env bash shebang in IDE mirror check-complete.sh files (drift from v2.35.1)

Adds tests/test_canonical_script_sync.py: byte-comparison assertion between
scripts/ and skills/planning-with-files/scripts/ for init-session and
check-complete, plus sync-ide-folders.py --verify assertion to catch IDE mirror
drift in CI going forward.

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "planning-with-files",
       "source": "./",
       "description": "Manus-style persistent markdown files for planning, progress tracking, and knowledge storage. Now with hooks integration and multi-language support (Arabic, German, Spanish, Chinese).",
-      "version": "2.36.1"
+      "version": "2.36.2"
     }
   ]
 }

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "planning-with-files",
-  "version": "2.36.1",
+  "version": "2.36.2",
   "description": "Manus-style persistent markdown files for planning, progress tracking, and knowledge storage. Works with Claude Code, Kiro, Clawd CLI, Gemini CLI, Cursor, Continue, Hermes, and 17+ AI coding assistants. Now with Arabic, German, Spanish, and Chinese (Simplified & Traditional) support.",
   "author": {
     "name": "OthmanAdi",

.codebuddy/skills/planning-with-files/SKILL.md

@@ -23,7 +23,7 @@ hooks:
         - type: command
           command: "SD=\"${CODEBUDDY_PLUGIN_ROOT:-$HOME/.codebuddy/skills/planning-with-files}/scripts\"; powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -File \"$SD/check-complete.ps1\" 2>/dev/null || sh \"$SD/check-complete.sh\""
 metadata:
-  version: "2.36.1"
+  version: "2.36.2"
 
 ---
 

.codebuddy/skills/planning-with-files/scripts/check-complete.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Check if all phases in task_plan.md are complete
 # Always exits 0 — uses stdout for status reporting
 # Used by Stop hook to report task completion status

.codebuddy/skills/planning-with-files/scripts/init-session.ps1

@@ -1,17 +1,34 @@
 # Initialize planning files for a new session
-# Usage: .\init-session.ps1 [project-name]
+# Usage: .\init-session.ps1 [-Template TYPE] [project-name]
+# Templates: default, analytics
 
 param(
-    [string]$ProjectName = "project"
+    [string]$ProjectName = "project",
+    [string]$Template = "default"
 )
 
 $DATE = Get-Date -Format "yyyy-MM-dd"
 
-Write-Host "Initializing planning files for: $ProjectName"
+# Resolve template directory (skill root is one level up from scripts/)
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$SkillRoot = Split-Path -Parent $ScriptDir
+$TemplateDir = Join-Path $SkillRoot "templates"
+
+Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
+
+# Validate template
+if ($Template -ne "default" -and $Template -ne "analytics") {
+    Write-Host "Unknown template: $Template (available: default, analytics). Using default."
+    $Template = "default"
+}
 
 # Create task_plan.md if it doesn't exist
 if (-not (Test-Path "task_plan.md")) {
-    @"
+    $AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
+    if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
+        Copy-Item $AnalyticsPlan "task_plan.md"
+    } else {
+        @"
 # Task Plan: [Brief Description]
 
 ## Goal
@@ -56,6 +73,7 @@ Phase 1
 | Error | Resolution |
 |-------|------------|
 "@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
+    }
     Write-Host "Created task_plan.md"
 } else {
     Write-Host "task_plan.md already exists, skipping"
@@ -63,7 +81,11 @@ Phase 1
 
 # Create findings.md if it doesn't exist
 if (-not (Test-Path "findings.md")) {
-    @"
+    $AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
+    if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
+        Copy-Item $AnalyticsFindings "findings.md"
+    } else {
+        @"
 # Findings & Decisions
 
 ## Requirements
@@ -83,6 +105,7 @@ if (-not (Test-Path "findings.md")) {
 ## Resources
 -
 "@ | Out-File -FilePath "findings.md" -Encoding UTF8
+    }
     Write-Host "Created findings.md"
 } else {
     Write-Host "findings.md already exists, skipping"
@@ -90,7 +113,29 @@ if (-not (Test-Path "findings.md")) {
 
 # Create progress.md if it doesn't exist
 if (-not (Test-Path "progress.md")) {
-    @"
+    if ($Template -eq "analytics") {
+        @"
+# Progress Log
+
+## Session: $DATE
+
+### Current Status
+- **Phase:** 1 - Data Discovery
+- **Started:** $DATE
+
+### Actions Taken
+-
+
+### Query Log
+| Query | Result Summary | Interpretation |
+|-------|---------------|----------------|
+
+### Errors
+| Error | Resolution |
+|-------|------------|
+"@ | Out-File -FilePath "progress.md" -Encoding UTF8
+    } else {
+        @"
 # Progress Log
 
 ## Session: $DATE
@@ -110,6 +155,7 @@ if (-not (Test-Path "progress.md")) {
 | Error | Resolution |
 |-------|------------|
 "@ | Out-File -FilePath "progress.md" -Encoding UTF8
+    }
     Write-Host "Created progress.md"
 } else {
     Write-Host "progress.md already exists, skipping"

.codebuddy/skills/planning-with-files/scripts/init-session.sh

@@ -1,17 +1,96 @@
-#!/bin/bash
-# Initialize planning files for a new session
-# Usage: ./init-session.sh [project-name]
+#!/usr/bin/env bash
+# Initialize planning files for a new session.
+#
+# Usage:
+#   ./init-session.sh                              # legacy: root-level task_plan.md, findings.md, progress.md
+#   ./init-session.sh [--template TYPE]            # legacy with template choice
+#   ./init-session.sh "Backend Refactor"           # slug mode: .planning/<date>-backend-refactor/
+#   ./init-session.sh --plan-dir                   # slug mode with auto-generated untitled-<short> name
+#   ./init-session.sh --plan-dir "Quick Spike"     # slug mode, explicit slug
+#
+# Legacy mode (zero positional args, no --plan-dir) preserves v1.x behavior so
+# upgrades stay non-breaking. Slug mode addresses parallel multi-task isolation
+# (issue #148) by writing each plan under .planning/<date>-<slug>/ and pinning
+# .planning/.active_plan so resolve-plan-dir.sh can find it.
 
 set -e
 
-PROJECT_NAME="${1:-project}"
+TEMPLATE="default"
+PROJECT_NAME=""
+USE_PLAN_DIR=0
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --template|-t)
+            TEMPLATE="$2"
+            shift 2
+            ;;
+        --plan-dir)
+            USE_PLAN_DIR=1
+            shift
+            ;;
+        *)
+            if [ -z "$PROJECT_NAME" ]; then
+                PROJECT_NAME="$1"
+            else
+                PROJECT_NAME="$PROJECT_NAME $1"
+            fi
+            shift
+            ;;
+    esac
+done
+
 DATE=$(date +%Y-%m-%d)
 
-echo "Initializing planning files for: $PROJECT_NAME"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SKILL_ROOT="$(dirname "$SCRIPT_DIR")"
+TEMPLATE_DIR="$SKILL_ROOT/templates"
 
-# Create task_plan.md if it doesn't exist
-if [ ! -f "task_plan.md" ]; then
-    cat > task_plan.md << 'EOF'
+if [ "$TEMPLATE" != "default" ] && [ "$TEMPLATE" != "analytics" ]; then
+    echo "Unknown template: $TEMPLATE (available: default, analytics). Using default."
+    TEMPLATE="default"
+fi
+
+# Slug mode triggers when a project name was given OR --plan-dir was passed.
+SLUG_MODE=0
+if [ -n "$PROJECT_NAME" ] || [ "$USE_PLAN_DIR" -eq 1 ]; then
+    SLUG_MODE=1
+fi
+
+slugify() {
+    # Lowercase, non-alphanumerics → '-', collapse repeats, trim leading/trailing '-'
+    printf '%s' "$1" \
+        | tr '[:upper:]' '[:lower:]' \
+        | sed -e 's/[^a-z0-9]/-/g' -e 's/-\{2,\}/-/g' -e 's/^-//' -e 's/-$//' \
+        | cut -c1-40
+}
+
+short_uuid() {
+    # Probe each candidate: command -v alone is not enough on Windows because
+    # App Execution Aliases report presence but exit non-zero when run.
+    _py="${PYTHON_BIN:-}"
+    if [ -z "$_py" ]; then
+        for _c in python3 python py; do
+            if command -v "$_c" >/dev/null 2>&1 && "$_c" -c "import uuid" >/dev/null 2>&1; then
+                _py="$_c"
+                break
+            fi
+        done
+    fi
+    if [ -n "$_py" ]; then
+        "$_py" -c "import uuid; print(uuid.uuid4().hex[:8])"
+        return
+    fi
+    if command -v uuidgen >/dev/null 2>&1; then
+        uuidgen | tr '[:upper:]' '[:lower:]' | tr -d '-' | cut -c1-8
+        return
+    fi
+    # Last-ditch: seconds timestamp as 8 hex chars
+    printf '%08x' "$(date +%s)" | cut -c1-8
+}
+
+write_default_task_plan() {
+    cat > "$1" << 'EOF'
 # Task Plan: [Brief Description]
 
 ## Goal
@@ -56,14 +135,10 @@ Phase 1
 | Error | Resolution |
 |-------|------------|
 EOF
-    echo "Created task_plan.md"
-else
-    echo "task_plan.md already exists, skipping"
-fi
+}
 
-# Create findings.md if it doesn't exist
-if [ ! -f "findings.md" ]; then
-    cat > findings.md << 'EOF'
+write_default_findings() {
+    cat > "$1" << 'EOF'
 # Findings & Decisions
 
 ## Requirements
@@ -83,21 +158,19 @@ if [ ! -f "findings.md" ]; then
 ## Resources
 -
 EOF
-    echo "Created findings.md"
-else
-    echo "findings.md already exists, skipping"
-fi
+}
 
-# Create progress.md if it doesn't exist
-if [ ! -f "progress.md" ]; then
-    cat > progress.md << EOF
+write_default_progress() {
+    local date_value="$1"
+    local target="$2"
+    cat > "$target" << EOF
 # Progress Log
 
-## Session: $DATE
+## Session: $date_value
 
 ### Current Status
 - **Phase:** 1 - Requirements & Discovery
-- **Started:** $DATE
+- **Started:** $date_value
 
 ### Actions Taken
 -
@@ -110,11 +183,102 @@ if [ ! -f "progress.md" ]; then
 | Error | Resolution |
 |-------|------------|
 EOF
-    echo "Created progress.md"
-else
-    echo "progress.md already exists, skipping"
-fi
+}
 
-echo ""
-echo "Planning files initialized!"
-echo "Files: task_plan.md, findings.md, progress.md"
+write_analytics_progress() {
+    local date_value="$1"
+    local target="$2"
+    cat > "$target" << EOF
+# Progress Log
+
+## Session: $date_value
+
+### Current Status
+- **Phase:** 1 - Data Discovery
+- **Started:** $date_value
+
+### Actions Taken
+-
+
+### Query Log
+| Query | Result Summary | Interpretation |
+|-------|---------------|----------------|
+
+### Errors
+| Error | Resolution |
+|-------|------------|
+EOF
+}
+
+create_files_in() {
+    local target_dir="$1"
+    local plan_path="$target_dir/task_plan.md"
+    local findings_path="$target_dir/findings.md"
+    local progress_path="$target_dir/progress.md"
+
+    if [ ! -f "$plan_path" ]; then
+        if [ "$TEMPLATE" = "analytics" ] && [ -f "$TEMPLATE_DIR/analytics_task_plan.md" ]; then
+            cp "$TEMPLATE_DIR/analytics_task_plan.md" "$plan_path"
+        else
+            write_default_task_plan "$plan_path"
+        fi
+        echo "Created $plan_path"
+    else
+        echo "$plan_path already exists, skipping"
+    fi
+
+    if [ ! -f "$findings_path" ]; then
+        if [ "$TEMPLATE" = "analytics" ] && [ -f "$TEMPLATE_DIR/analytics_findings.md" ]; then
+            cp "$TEMPLATE_DIR/analytics_findings.md" "$findings_path"
+        else
+            write_default_findings "$findings_path"
+        fi
+        echo "Created $findings_path"
+    else
+        echo "$findings_path already exists, skipping"
+    fi
+
+    if [ ! -f "$progress_path" ]; then
+        if [ "$TEMPLATE" = "analytics" ]; then
+            write_analytics_progress "$DATE" "$progress_path"
+        else
+            write_default_progress "$DATE" "$progress_path"
+        fi
+        echo "Created $progress_path"
+    else
+        echo "$progress_path already exists, skipping"
+    fi
+}
+
+if [ "$SLUG_MODE" -eq 1 ]; then
+    SLUG="$(slugify "$PROJECT_NAME")"
+    if [ -z "$SLUG" ]; then
+        SLUG="untitled-$(short_uuid)"
+    fi
+    BASE_ID="${DATE}-${SLUG}"
+    PLAN_ID="$BASE_ID"
+    PLAN_ROOT="${PWD}/.planning"
+    counter=2
+    while [ -d "${PLAN_ROOT}/${PLAN_ID}" ]; do
+        PLAN_ID="${BASE_ID}-${counter}"
+        counter=$((counter + 1))
+    done
+    PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
+    mkdir -p "$PLAN_DIR"
+
+    echo "Initializing planning files for: ${PROJECT_NAME:-untitled} (template: $TEMPLATE)"
+    echo "PLAN_ID=$PLAN_ID"
+    create_files_in "$PLAN_DIR"
+    printf "%s\n" "$PLAN_ID" > "${PLAN_ROOT}/.active_plan"
+    echo ""
+    echo "Active plan recorded: ${PLAN_ROOT}/.active_plan"
+    echo "Pin this terminal to the plan for parallel sessions:"
+    echo "  export PLAN_ID=$PLAN_ID"
+else
+    PROJECT_NAME="${PROJECT_NAME:-project}"
+    echo "Initializing planning files for: $PROJECT_NAME (template: $TEMPLATE)"
+    create_files_in "$(pwd)"
+    echo ""
+    echo "Planning files initialized!"
+    echo "Files: task_plan.md, findings.md, progress.md"
+fi

.codex/skills/planning-with-files/SKILL.md

@@ -23,7 +23,7 @@ hooks:
         - type: command
           command: "SD=\"${CODEX_SKILL_ROOT:-$HOME/.codex/skills/planning-with-files}/scripts\"; powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -File \"$SD/check-complete.ps1\" 2>/dev/null || sh \"$SD/check-complete.sh\""
 metadata:
-  version: "2.36.1"
+  version: "2.36.2"
 
 ---
 

.codex/skills/planning-with-files/scripts/check-complete.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Check if all phases in task_plan.md are complete
 # Always exits 0 — uses stdout for status reporting
 # Used by Stop hook to report task completion status

.codex/skills/planning-with-files/scripts/init-session.ps1

@@ -1,17 +1,34 @@
 # Initialize planning files for a new session
-# Usage: .\init-session.ps1 [project-name]
+# Usage: .\init-session.ps1 [-Template TYPE] [project-name]
+# Templates: default, analytics
 
 param(
-    [string]$ProjectName = "project"
+    [string]$ProjectName = "project",
+    [string]$Template = "default"
 )
 
 $DATE = Get-Date -Format "yyyy-MM-dd"
 
-Write-Host "Initializing planning files for: $ProjectName"
+# Resolve template directory (skill root is one level up from scripts/)
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$SkillRoot = Split-Path -Parent $ScriptDir
+$TemplateDir = Join-Path $SkillRoot "templates"
+
+Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
+
+# Validate template
+if ($Template -ne "default" -and $Template -ne "analytics") {
+    Write-Host "Unknown template: $Template (available: default, analytics). Using default."
+    $Template = "default"
+}
 
 # Create task_plan.md if it doesn't exist
 if (-not (Test-Path "task_plan.md")) {
-    @"
+    $AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
+    if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
+        Copy-Item $AnalyticsPlan "task_plan.md"
+    } else {
+        @"
 # Task Plan: [Brief Description]
 
 ## Goal
@@ -56,6 +73,7 @@ Phase 1
 | Error | Resolution |
 |-------|------------|
 "@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
+    }
     Write-Host "Created task_plan.md"
 } else {
     Write-Host "task_plan.md already exists, skipping"
@@ -63,7 +81,11 @@ Phase 1
 
 # Create findings.md if it doesn't exist
 if (-not (Test-Path "findings.md")) {
-    @"
+    $AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
+    if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
+        Copy-Item $AnalyticsFindings "findings.md"
+    } else {
+        @"
 # Findings & Decisions
 
 ## Requirements
@@ -83,6 +105,7 @@ if (-not (Test-Path "findings.md")) {
 ## Resources
 -
 "@ | Out-File -FilePath "findings.md" -Encoding UTF8
+    }
     Write-Host "Created findings.md"
 } else {
     Write-Host "findings.md already exists, skipping"
@@ -90,7 +113,29 @@ if (-not (Test-Path "findings.md")) {
 
 # Create progress.md if it doesn't exist
 if (-not (Test-Path "progress.md")) {
-    @"
+    if ($Template -eq "analytics") {
+        @"
+# Progress Log
+
+## Session: $DATE
+
+### Current Status
+- **Phase:** 1 - Data Discovery
+- **Started:** $DATE
+
+### Actions Taken
+-
+
+### Query Log
+| Query | Result Summary | Interpretation |
+|-------|---------------|----------------|
+
+### Errors
+| Error | Resolution |
+|-------|------------|
+"@ | Out-File -FilePath "progress.md" -Encoding UTF8
+    } else {
+        @"
 # Progress Log
 
 ## Session: $DATE
@@ -110,6 +155,7 @@ if (-not (Test-Path "progress.md")) {
 | Error | Resolution |
 |-------|------------|
 "@ | Out-File -FilePath "progress.md" -Encoding UTF8
+    }
     Write-Host "Created progress.md"
 } else {
     Write-Host "progress.md already exists, skipping"

.codex/skills/planning-with-files/scripts/init-session.sh

@@ -1,17 +1,96 @@
-#!/bin/bash
-# Initialize planning files for a new session
-# Usage: ./init-session.sh [project-name]
+#!/usr/bin/env bash
+# Initialize planning files for a new session.
+#
+# Usage:
+#   ./init-session.sh                              # legacy: root-level task_plan.md, findings.md, progress.md
+#   ./init-session.sh [--template TYPE]            # legacy with template choice
+#   ./init-session.sh "Backend Refactor"           # slug mode: .planning/<date>-backend-refactor/
+#   ./init-session.sh --plan-dir                   # slug mode with auto-generated untitled-<short> name
+#   ./init-session.sh --plan-dir "Quick Spike"     # slug mode, explicit slug
+#
+# Legacy mode (zero positional args, no --plan-dir) preserves v1.x behavior so
+# upgrades stay non-breaking. Slug mode addresses parallel multi-task isolation
+# (issue #148) by writing each plan under .planning/<date>-<slug>/ and pinning
+# .planning/.active_plan so resolve-plan-dir.sh can find it.
 
 set -e
 
-PROJECT_NAME="${1:-project}"
+TEMPLATE="default"
+PROJECT_NAME=""
+USE_PLAN_DIR=0
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --template|-t)
+            TEMPLATE="$2"
+            shift 2
+            ;;
+        --plan-dir)
+            USE_PLAN_DIR=1
+            shift
+            ;;
+        *)
+            if [ -z "$PROJECT_NAME" ]; then
+                PROJECT_NAME="$1"
+            else
+                PROJECT_NAME="$PROJECT_NAME $1"
+            fi
+            shift
+            ;;
+    esac
+done
+
 DATE=$(date +%Y-%m-%d)
 
-echo "Initializing planning files for: $PROJECT_NAME"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SKILL_ROOT="$(dirname "$SCRIPT_DIR")"
+TEMPLATE_DIR="$SKILL_ROOT/templates"
 
-# Create task_plan.md if it doesn't exist
-if [ ! -f "task_plan.md" ]; then
-    cat > task_plan.md << 'EOF'
+if [ "$TEMPLATE" != "default" ] && [ "$TEMPLATE" != "analytics" ]; then
+    echo "Unknown template: $TEMPLATE (available: default, analytics). Using default."
+    TEMPLATE="default"
+fi
+
+# Slug mode triggers when a project name was given OR --plan-dir was passed.
+SLUG_MODE=0
+if [ -n "$PROJECT_NAME" ] || [ "$USE_PLAN_DIR" -eq 1 ]; then
+    SLUG_MODE=1
+fi
+
+slugify() {
+    # Lowercase, non-alphanumerics → '-', collapse repeats, trim leading/trailing '-'
+    printf '%s' "$1" \
+        | tr '[:upper:]' '[:lower:]' \
+        | sed -e 's/[^a-z0-9]/-/g' -e 's/-\{2,\}/-/g' -e 's/^-//' -e 's/-$//' \
+        | cut -c1-40
+}
+
+short_uuid() {
+    # Probe each candidate: command -v alone is not enough on Windows because
+    # App Execution Aliases report presence but exit non-zero when run.
+    _py="${PYTHON_BIN:-}"
+    if [ -z "$_py" ]; then
+        for _c in python3 python py; do
+            if command -v "$_c" >/dev/null 2>&1 && "$_c" -c "import uuid" >/dev/null 2>&1; then
+                _py="$_c"
+                break
+            fi
+        done
+    fi
+    if [ -n "$_py" ]; then
+        "$_py" -c "import uuid; print(uuid.uuid4().hex[:8])"
+        return
+    fi
+    if command -v uuidgen >/dev/null 2>&1; then
+        uuidgen | tr '[:upper:]' '[:lower:]' | tr -d '-' | cut -c1-8
+        return
+    fi
+    # Last-ditch: seconds timestamp as 8 hex chars
+    printf '%08x' "$(date +%s)" | cut -c1-8
+}
+
+write_default_task_plan() {
+    cat > "$1" << 'EOF'
 # Task Plan: [Brief Description]
 
 ## Goal
@@ -56,14 +135,10 @@ Phase 1
 | Error | Resolution |
 |-------|------------|
 EOF
-    echo "Created task_plan.md"
-else
-    echo "task_plan.md already exists, skipping"
-fi
+}
 
-# Create findings.md if it doesn't exist
-if [ ! -f "findings.md" ]; then
-    cat > findings.md << 'EOF'
+write_default_findings() {
+    cat > "$1" << 'EOF'
 # Findings & Decisions
 
 ## Requirements
@@ -83,21 +158,19 @@ if [ ! -f "findings.md" ]; then
 ## Resources
 -
 EOF
-    echo "Created findings.md"
-else
-    echo "findings.md already exists, skipping"
-fi
+}
 
-# Create progress.md if it doesn't exist
-if [ ! -f "progress.md" ]; then
-    cat > progress.md << EOF
+write_default_progress() {
+    local date_value="$1"
+    local target="$2"
+    cat > "$target" << EOF
 # Progress Log
 
-## Session: $DATE
+## Session: $date_value
 
 ### Current Status
 - **Phase:** 1 - Requirements & Discovery
-- **Started:** $DATE
+- **Started:** $date_value
 
 ### Actions Taken
 -
@@ -110,11 +183,102 @@ if [ ! -f "progress.md" ]; then
 | Error | Resolution |
 |-------|------------|
 EOF
-    echo "Created progress.md"
-else
-    echo "progress.md already exists, skipping"
-fi
+}
 
-echo ""
-echo "Planning files initialized!"
-echo "Files: task_plan.md, findings.md, progress.md"
+write_analytics_progress() {
+    local date_value="$1"
+    local target="$2"
+    cat > "$target" << EOF
+# Progress Log
+
+## Session: $date_value
+
+### Current Status
+- **Phase:** 1 - Data Discovery
+- **Started:** $date_value
+
+### Actions Taken
+-
+
+### Query Log
+| Query | Result Summary | Interpretation |
+|-------|---------------|----------------|
+
+### Errors
+| Error | Resolution |
+|-------|------------|
+EOF
+}
+
+create_files_in() {
+    local target_dir="$1"
+    local plan_path="$target_dir/task_plan.md"
+    local findings_path="$target_dir/findings.md"
+    local progress_path="$target_dir/progress.md"
+
+    if [ ! -f "$plan_path" ]; then
+        if [ "$TEMPLATE" = "analytics" ] && [ -f "$TEMPLATE_DIR/analytics_task_plan.md" ]; then
+            cp "$TEMPLATE_DIR/analytics_task_plan.md" "$plan_path"
+        else
+            write_default_task_plan "$plan_path"
+        fi
+        echo "Created $plan_path"
+    else
+        echo "$plan_path already exists, skipping"
+    fi
+
+    if [ ! -f "$findings_path" ]; then
+        if [ "$TEMPLATE" = "analytics" ] && [ -f "$TEMPLATE_DIR/analytics_findings.md" ]; then
+            cp "$TEMPLATE_DIR/analytics_findings.md" "$findings_path"
+        else
+            write_default_findings "$findings_path"
+        fi
+        echo "Created $findings_path"
+    else
+        echo "$findings_path already exists, skipping"
+    fi
+
+    if [ ! -f "$progress_path" ]; then
+        if [ "$TEMPLATE" = "analytics" ]; then
+            write_analytics_progress "$DATE" "$progress_path"
+        else
+            write_default_progress "$DATE" "$progress_path"
+        fi
+        echo "Created $progress_path"
+    else
+        echo "$progress_path already exists, skipping"
+    fi
+}
+
+if [ "$SLUG_MODE" -eq 1 ]; then
+    SLUG="$(slugify "$PROJECT_NAME")"
+    if [ -z "$SLUG" ]; then
+        SLUG="untitled-$(short_uuid)"
+    fi
+    BASE_ID="${DATE}-${SLUG}"
+    PLAN_ID="$BASE_ID"
+    PLAN_ROOT="${PWD}/.planning"
+    counter=2
+    while [ -d "${PLAN_ROOT}/${PLAN_ID}" ]; do
+        PLAN_ID="${BASE_ID}-${counter}"
+        counter=$((counter + 1))
+    done
+    PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
+    mkdir -p "$PLAN_DIR"
+
+    echo "Initializing planning files for: ${PROJECT_NAME:-untitled} (template: $TEMPLATE)"
+    echo "PLAN_ID=$PLAN_ID"
+    create_files_in "$PLAN_DIR"
+    printf "%s\n" "$PLAN_ID" > "${PLAN_ROOT}/.active_plan"
+    echo ""
+    echo "Active plan recorded: ${PLAN_ROOT}/.active_plan"
+    echo "Pin this terminal to the plan for parallel sessions:"
+    echo "  export PLAN_ID=$PLAN_ID"
+else
+    PROJECT_NAME="${PROJECT_NAME:-project}"
+    echo "Initializing planning files for: $PROJECT_NAME (template: $TEMPLATE)"
+    create_files_in "$(pwd)"
+    echo ""
+    echo "Planning files initialized!"
+    echo "Files: task_plan.md, findings.md, progress.md"
+fi

.continue/skills/planning-with-files/scripts/check-complete.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Check if all phases in task_plan.md are complete
 # Always exits 0 — uses stdout for status reporting
 # Used by Stop hook to report task completion status

.continue/skills/planning-with-files/scripts/init-session.ps1

@@ -1,17 +1,34 @@
 # Initialize planning files for a new session
-# Usage: .\init-session.ps1 [project-name]
+# Usage: .\init-session.ps1 [-Template TYPE] [project-name]
+# Templates: default, analytics
 
 param(
-    [string]$ProjectName = "project"
+    [string]$ProjectName = "project",
+    [string]$Template = "default"
 )
 
 $DATE = Get-Date -Format "yyyy-MM-dd"
 
-Write-Host "Initializing planning files for: $ProjectName"
+# Resolve template directory (skill root is one level up from scripts/)
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$SkillRoot = Split-Path -Parent $ScriptDir
+$TemplateDir = Join-Path $SkillRoot "templates"
+
+Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
+
+# Validate template
+if ($Template -ne "default" -and $Template -ne "analytics") {
+    Write-Host "Unknown template: $Template (available: default, analytics). Using default."
+    $Template = "default"
+}
 
 # Create task_plan.md if it doesn't exist
 if (-not (Test-Path "task_plan.md")) {
-    @"
+    $AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
+    if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
+        Copy-Item $AnalyticsPlan "task_plan.md"
+    } else {
+        @"
 # Task Plan: [Brief Description]
 
 ## Goal
@@ -56,6 +73,7 @@ Phase 1
 | Error | Resolution |
 |-------|------------|
 "@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
+    }
     Write-Host "Created task_plan.md"
 } else {
     Write-Host "task_plan.md already exists, skipping"
@@ -63,7 +81,11 @@ Phase 1
 
 # Create findings.md if it doesn't exist
 if (-not (Test-Path "findings.md")) {
-    @"
+    $AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
+    if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
+        Copy-Item $AnalyticsFindings "findings.md"
+    } else {
+        @"
 # Findings & Decisions
 
 ## Requirements
@@ -83,6 +105,7 @@ if (-not (Test-Path "findings.md")) {
 ## Resources
 -
 "@ | Out-File -FilePath "findings.md" -Encoding UTF8
+    }
     Write-Host "Created findings.md"
 } else {
     Write-Host "findings.md already exists, skipping"
@@ -90,7 +113,29 @@ if (-not (Test-Path "findings.md")) {
 
 # Create progress.md if it doesn't exist
 if (-not (Test-Path "progress.md")) {
-    @"
+    if ($Template -eq "analytics") {
+        @"
+# Progress Log
+
+## Session: $DATE
+
+### Current Status
+- **Phase:** 1 - Data Discovery
+- **Started:** $DATE
+
+### Actions Taken
+-
+
+### Query Log
+| Query | Result Summary | Interpretation |
+|-------|---------------|----------------|
+
+### Errors
+| Error | Resolution |
+|-------|------------|
+"@ | Out-File -FilePath "progress.md" -Encoding UTF8
+    } else {
+        @"
 # Progress Log
 
 ## Session: $DATE
@@ -110,6 +155,7 @@ if (-not (Test-Path "progress.md")) {
 | Error | Resolution |
 |-------|------------|
 "@ | Out-File -FilePath "progress.md" -Encoding UTF8
+    }
     Write-Host "Created progress.md"
 } else {
     Write-Host "progress.md already exists, skipping"

.continue/skills/planning-with-files/scripts/init-session.sh

@@ -1,17 +1,96 @@
-#!/bin/bash
-# Initialize planning files for a new session
-# Usage: ./init-session.sh [project-name]
+#!/usr/bin/env bash
+# Initialize planning files for a new session.
+#
+# Usage:
+#   ./init-session.sh                              # legacy: root-level task_plan.md, findings.md, progress.md
+#   ./init-session.sh [--template TYPE]            # legacy with template choice
+#   ./init-session.sh "Backend Refactor"           # slug mode: .planning/<date>-backend-refactor/
+#   ./init-session.sh --plan-dir                   # slug mode with auto-generated untitled-<short> name
+#   ./init-session.sh --plan-dir "Quick Spike"     # slug mode, explicit slug
+#
+# Legacy mode (zero positional args, no --plan-dir) preserves v1.x behavior so
+# upgrades stay non-breaking. Slug mode addresses parallel multi-task isolation
+# (issue #148) by writing each plan under .planning/<date>-<slug>/ and pinning
+# .planning/.active_plan so resolve-plan-dir.sh can find it.
 
 set -e
 
-PROJECT_NAME="${1:-project}"
+TEMPLATE="default"
+PROJECT_NAME=""
+USE_PLAN_DIR=0
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --template|-t)
+            TEMPLATE="$2"
+            shift 2
+            ;;
+        --plan-dir)
+            USE_PLAN_DIR=1
+            shift
+            ;;
+        *)
+            if [ -z "$PROJECT_NAME" ]; then
+                PROJECT_NAME="$1"
+            else
+                PROJECT_NAME="$PROJECT_NAME $1"
+            fi
+            shift
+            ;;
+    esac
+done
+
 DATE=$(date +%Y-%m-%d)
 
-echo "Initializing planning files for: $PROJECT_NAME"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SKILL_ROOT="$(dirname "$SCRIPT_DIR")"
+TEMPLATE_DIR="$SKILL_ROOT/templates"
 
-# Create task_plan.md if it doesn't exist
-if [ ! -f "task_plan.md" ]; then
-    cat > task_plan.md << 'EOF'
+if [ "$TEMPLATE" != "default" ] && [ "$TEMPLATE" != "analytics" ]; then
+    echo "Unknown template: $TEMPLATE (available: default, analytics). Using default."
+    TEMPLATE="default"
+fi
+
+# Slug mode triggers when a project name was given OR --plan-dir was passed.
+SLUG_MODE=0
+if [ -n "$PROJECT_NAME" ] || [ "$USE_PLAN_DIR" -eq 1 ]; then
+    SLUG_MODE=1
+fi
+
+slugify() {
+    # Lowercase, non-alphanumerics → '-', collapse repeats, trim leading/trailing '-'
+    printf '%s' "$1" \
+        | tr '[:upper:]' '[:lower:]' \
+        | sed -e 's/[^a-z0-9]/-/g' -e 's/-\{2,\}/-/g' -e 's/^-//' -e 's/-$//' \
+        | cut -c1-40
+}
+
+short_uuid() {
+    # Probe each candidate: command -v alone is not enough on Windows because
+    # App Execution Aliases report presence but exit non-zero when run.
+    _py="${PYTHON_BIN:-}"
+    if [ -z "$_py" ]; then
+        for _c in python3 python py; do
+            if command -v "$_c" >/dev/null 2>&1 && "$_c" -c "import uuid" >/dev/null 2>&1; then
+                _py="$_c"
+                break
+            fi
+        done
+    fi
+    if [ -n "$_py" ]; then
+        "$_py" -c "import uuid; print(uuid.uuid4().hex[:8])"
+        return
+    fi
+    if command -v uuidgen >/dev/null 2>&1; then
+        uuidgen | tr '[:upper:]' '[:lower:]' | tr -d '-' | cut -c1-8
+        return
+    fi
+    # Last-ditch: seconds timestamp as 8 hex chars
+    printf '%08x' "$(date +%s)" | cut -c1-8
+}
+
+write_default_task_plan() {
+    cat > "$1" << 'EOF'
 # Task Plan: [Brief Description]
 
 ## Goal
@@ -56,14 +135,10 @@ Phase 1
 | Error | Resolution |
 |-------|------------|
 EOF
-    echo "Created task_plan.md"
-else
-    echo "task_plan.md already exists, skipping"
-fi
+}
 
-# Create findings.md if it doesn't exist
-if [ ! -f "findings.md" ]; then
-    cat > findings.md << 'EOF'
+write_default_findings() {
+    cat > "$1" << 'EOF'
 # Findings & Decisions
 
 ## Requirements
@@ -83,21 +158,19 @@ if [ ! -f "findings.md" ]; then
 ## Resources
 -
 EOF
-    echo "Created findings.md"
-else
-    echo "findings.md already exists, skipping"
-fi
+}
 
-# Create progress.md if it doesn't exist
-if [ ! -f "progress.md" ]; then
-    cat > progress.md << EOF
+write_default_progress() {
+    local date_value="$1"
+    local target="$2"
+    cat > "$target" << EOF
 # Progress Log
 
-## Session: $DATE
+## Session: $date_value
 
 ### Current Status
 - **Phase:** 1 - Requirements & Discovery
-- **Started:** $DATE
+- **Started:** $date_value
 
 ### Actions Taken
 -
@@ -110,11 +183,102 @@ if [ ! -f "progress.md" ]; then
 | Error | Resolution |
 |-------|------------|
 EOF
-    echo "Created progress.md"
-else
-    echo "progress.md already exists, skipping"
-fi
+}
 
-echo ""
-echo "Planning files initialized!"
-echo "Files: task_plan.md, findings.md, progress.md"
+write_analytics_progress() {
+    local date_value="$1"
+    local target="$2"
+    cat > "$target" << EOF
+# Progress Log
+
+## Session: $date_value
+
+### Current Status
+- **Phase:** 1 - Data Discovery
+- **Started:** $date_value
+
+### Actions Taken
+-
+
+### Query Log
+| Query | Result Summary | Interpretation |
+|-------|---------------|----------------|
+
+### Errors
+| Error | Resolution |
+|-------|------------|
+EOF
+}
+
+create_files_in() {
+    local target_dir="$1"
+    local plan_path="$target_dir/task_plan.md"
+    local findings_path="$target_dir/findings.md"
+    local progress_path="$target_dir/progress.md"
+
+    if [ ! -f "$plan_path" ]; then
+        if [ "$TEMPLATE" = "analytics" ] && [ -f "$TEMPLATE_DIR/analytics_task_plan.md" ]; then
+            cp "$TEMPLATE_DIR/analytics_task_plan.md" "$plan_path"
+        else
+            write_default_task_plan "$plan_path"
+        fi
+        echo "Created $plan_path"
+    else
+        echo "$plan_path already exists, skipping"
+    fi
+
+    if [ ! -f "$findings_path" ]; then
+        if [ "$TEMPLATE" = "analytics" ] && [ -f "$TEMPLATE_DIR/analytics_findings.md" ]; then
+            cp "$TEMPLATE_DIR/analytics_findings.md" "$findings_path"
+        else
+            write_default_findings "$findings_path"
+        fi
+        echo "Created $findings_path"
+    else
+        echo "$findings_path already exists, skipping"
+    fi
+
+    if [ ! -f "$progress_path" ]; then
+        if [ "$TEMPLATE" = "analytics" ]; then
+            write_analytics_progress "$DATE" "$progress_path"
+        else
+            write_default_progress "$DATE" "$progress_path"
+        fi
+        echo "Created $progress_path"
+    else
+        echo "$progress_path already exists, skipping"
+    fi
+}
+
+if [ "$SLUG_MODE" -eq 1 ]; then
+    SLUG="$(slugify "$PROJECT_NAME")"
+    if [ -z "$SLUG" ]; then
+        SLUG="untitled-$(short_uuid)"
+    fi
+    BASE_ID="${DATE}-${SLUG}"
+    PLAN_ID="$BASE_ID"
+    PLAN_ROOT="${PWD}/.planning"
+    counter=2
+    while [ -d "${PLAN_ROOT}/${PLAN_ID}" ]; do
+        PLAN_ID="${BASE_ID}-${counter}"
+        counter=$((counter + 1))
+    done
+    PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
+    mkdir -p "$PLAN_DIR"
+
+    echo "Initializing planning files for: ${PROJECT_NAME:-untitled} (template: $TEMPLATE)"
+    echo "PLAN_ID=$PLAN_ID"
+    create_files_in "$PLAN_DIR"
+    printf "%s\n" "$PLAN_ID" > "${PLAN_ROOT}/.active_plan"
+    echo ""
+    echo "Active plan recorded: ${PLAN_ROOT}/.active_plan"
+    echo "Pin this terminal to the plan for parallel sessions:"
+    echo "  export PLAN_ID=$PLAN_ID"
+else
+    PROJECT_NAME="${PROJECT_NAME:-project}"
+    echo "Initializing planning files for: $PROJECT_NAME (template: $TEMPLATE)"
+    create_files_in "$(pwd)"
+    echo ""
+    echo "Planning files initialized!"
+    echo "Files: task_plan.md, findings.md, progress.md"
+fi

.cursor/skills/planning-with-files/SKILL.md

@@ -23,7 +23,7 @@ hooks:
         - type: command
           command: "SD=\"${CURSOR_SKILL_ROOT:-.cursor/skills/planning-with-files}/scripts\"; powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -File \"$SD/check-complete.ps1\" 2>/dev/null || sh \"$SD/check-complete.sh\""
 metadata:
-  version: "2.36.1"
+  version: "2.36.2"
 
 ---
 

.factory/skills/planning-with-files/SKILL.md

@@ -23,7 +23,7 @@ hooks:
         - type: command
           command: "SD=\"${FACTORY_PROJECT_DIR:-.factory/skills/planning-with-files}/scripts\"; sh \"$SD/check-complete.sh\" 2>/dev/null || true"
 metadata:
-  version: "2.36.1"
+  version: "2.36.2"
 ---
 
 # Planning with Files

.factory/skills/planning-with-files/scripts/check-complete.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Check if all phases in task_plan.md are complete
 # Always exits 0 — uses stdout for status reporting
 # Used by Stop hook to report task completion status

.factory/skills/planning-with-files/scripts/init-session.ps1

@@ -1,17 +1,34 @@
 # Initialize planning files for a new session
-# Usage: .\init-session.ps1 [project-name]
+# Usage: .\init-session.ps1 [-Template TYPE] [project-name]
+# Templates: default, analytics
 
 param(
-    [string]$ProjectName = "project"
+    [string]$ProjectName = "project",
+    [string]$Template = "default"
 )
 
 $DATE = Get-Date -Format "yyyy-MM-dd"
 
-Write-Host "Initializing planning files for: $ProjectName"
+# Resolve template directory (skill root is one level up from scripts/)
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$SkillRoot = Split-Path -Parent $ScriptDir
+$TemplateDir = Join-Path $SkillRoot "templates"
+
+Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
+
+# Validate template
+if ($Template -ne "default" -and $Template -ne "analytics") {
+    Write-Host "Unknown template: $Template (available: default, analytics). Using default."
+    $Template = "default"
+}
 
 # Create task_plan.md if it doesn't exist
 if (-not (Test-Path "task_plan.md")) {
-    @"
+    $AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
+    if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
+        Copy-Item $AnalyticsPlan "task_plan.md"
+    } else {
+        @"
 # Task Plan: [Brief Description]
 
 ## Goal
@@ -56,6 +73,7 @@ Phase 1
 | Error | Resolution |
 |-------|------------|
 "@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
+    }
     Write-Host "Created task_plan.md"
 } else {
     Write-Host "task_plan.md already exists, skipping"
@@ -63,7 +81,11 @@ Phase 1
 
 # Create findings.md if it doesn't exist
 if (-not (Test-Path "findings.md")) {
-    @"
+    $AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
+    if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
+        Copy-Item $AnalyticsFindings "findings.md"
+    } else {
+        @"
 # Findings & Decisions
 
 ## Requirements
@@ -83,6 +105,7 @@ if (-not (Test-Path "findings.md")) {
 ## Resources
 -
 "@ | Out-File -FilePath "findings.md" -Encoding UTF8
+    }
     Write-Host "Created findings.md"
 } else {
     Write-Host "findings.md already exists, skipping"
@@ -90,7 +113,29 @@ if (-not (Test-Path "findings.md")) {
 
 # Create progress.md if it doesn't exist
 if (-not (Test-Path "progress.md")) {
-    @"
+    if ($Template -eq "analytics") {
+        @"
+# Progress Log
+
+## Session: $DATE
+
+### Current Status
+- **Phase:** 1 - Data Discovery
+- **Started:** $DATE
+
+### Actions Taken
+-
+
+### Query Log
+| Query | Result Summary | Interpretation |
+|-------|---------------|----------------|
+
+### Errors
+| Error | Resolution |
+|-------|------------|
+"@ | Out-File -FilePath "progress.md" -Encoding UTF8
+    } else {
+        @"
 # Progress Log
 
 ## Session: $DATE
@@ -110,6 +155,7 @@ if (-not (Test-Path "progress.md")) {
 | Error | Resolution |
 |-------|------------|
 "@ | Out-File -FilePath "progress.md" -Encoding UTF8
+    }
     Write-Host "Created progress.md"
 } else {
     Write-Host "progress.md already exists, skipping"

.factory/skills/planning-with-files/scripts/init-session.sh

@@ -1,17 +1,96 @@
-#!/bin/bash
-# Initialize planning files for a new session
-# Usage: ./init-session.sh [project-name]
+#!/usr/bin/env bash
+# Initialize planning files for a new session.
+#
+# Usage:
+#   ./init-session.sh                              # legacy: root-level task_plan.md, findings.md, progress.md
+#   ./init-session.sh [--template TYPE]            # legacy with template choice
+#   ./init-session.sh "Backend Refactor"           # slug mode: .planning/<date>-backend-refactor/
+#   ./init-session.sh --plan-dir                   # slug mode with auto-generated untitled-<short> name
+#   ./init-session.sh --plan-dir "Quick Spike"     # slug mode, explicit slug
+#
+# Legacy mode (zero positional args, no --plan-dir) preserves v1.x behavior so
+# upgrades stay non-breaking. Slug mode addresses parallel multi-task isolation
+# (issue #148) by writing each plan under .planning/<date>-<slug>/ and pinning
+# .planning/.active_plan so resolve-plan-dir.sh can find it.
 
 set -e
 
-PROJECT_NAME="${1:-project}"
+TEMPLATE="default"
+PROJECT_NAME=""
+USE_PLAN_DIR=0
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --template|-t)
+            TEMPLATE="$2"
+            shift 2
+            ;;
+        --plan-dir)
+            USE_PLAN_DIR=1
+            shift
+            ;;
+        *)
+            if [ -z "$PROJECT_NAME" ]; then
+                PROJECT_NAME="$1"
+            else
+                PROJECT_NAME="$PROJECT_NAME $1"
+            fi
+            shift
+            ;;
+    esac
+done
+
 DATE=$(date +%Y-%m-%d)
 
-echo "Initializing planning files for: $PROJECT_NAME"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SKILL_ROOT="$(dirname "$SCRIPT_DIR")"
+TEMPLATE_DIR="$SKILL_ROOT/templates"
 
-# Create task_plan.md if it doesn't exist
-if [ ! -f "task_plan.md" ]; then
-    cat > task_plan.md << 'EOF'
+if [ "$TEMPLATE" != "default" ] && [ "$TEMPLATE" != "analytics" ]; then
+    echo "Unknown template: $TEMPLATE (available: default, analytics). Using default."
+    TEMPLATE="default"
+fi
+
+# Slug mode triggers when a project name was given OR --plan-dir was passed.
+SLUG_MODE=0
+if [ -n "$PROJECT_NAME" ] || [ "$USE_PLAN_DIR" -eq 1 ]; then
+    SLUG_MODE=1
+fi
+
+slugify() {
+    # Lowercase, non-alphanumerics → '-', collapse repeats, trim leading/trailing '-'
+    printf '%s' "$1" \
+        | tr '[:upper:]' '[:lower:]' \
+        | sed -e 's/[^a-z0-9]/-/g' -e 's/-\{2,\}/-/g' -e 's/^-//' -e 's/-$//' \
+        | cut -c1-40
+}
+
+short_uuid() {
+    # Probe each candidate: command -v alone is not enough on Windows because
+    # App Execution Aliases report presence but exit non-zero when run.
+    _py="${PYTHON_BIN:-}"
+    if [ -z "$_py" ]; then
+        for _c in python3 python py; do
+            if command -v "$_c" >/dev/null 2>&1 && "$_c" -c "import uuid" >/dev/null 2>&1; then
+                _py="$_c"
+                break
+            fi
+        done
+    fi
+    if [ -n "$_py" ]; then
+        "$_py" -c "import uuid; print(uuid.uuid4().hex[:8])"
+        return
+    fi
+    if command -v uuidgen >/dev/null 2>&1; then
+        uuidgen | tr '[:upper:]' '[:lower:]' | tr -d '-' | cut -c1-8
+        return
+    fi
+    # Last-ditch: seconds timestamp as 8 hex chars
+    printf '%08x' "$(date +%s)" | cut -c1-8
+}
+
+write_default_task_plan() {
+    cat > "$1" << 'EOF'
 # Task Plan: [Brief Description]
 
 ## Goal
@@ -56,14 +135,10 @@ Phase 1
 | Error | Resolution |
 |-------|------------|
 EOF
-    echo "Created task_plan.md"
-else
-    echo "task_plan.md already exists, skipping"
-fi
+}
 
-# Create findings.md if it doesn't exist
-if [ ! -f "findings.md" ]; then
-    cat > findings.md << 'EOF'
+write_default_findings() {
+    cat > "$1" << 'EOF'
 # Findings & Decisions
 
 ## Requirements
@@ -83,21 +158,19 @@ if [ ! -f "findings.md" ]; then
 ## Resources
 -
 EOF
-    echo "Created findings.md"
-else
-    echo "findings.md already exists, skipping"
-fi
+}
 
-# Create progress.md if it doesn't exist
-if [ ! -f "progress.md" ]; then
-    cat > progress.md << EOF
+write_default_progress() {
+    local date_value="$1"
+    local target="$2"
+    cat > "$target" << EOF
 # Progress Log
 
-## Session: $DATE
+## Session: $date_value
 
 ### Current Status
 - **Phase:** 1 - Requirements & Discovery
-- **Started:** $DATE
+- **Started:** $date_value
 
 ### Actions Taken
 -
@@ -110,11 +183,102 @@ if [ ! -f "progress.md" ]; then
 | Error | Resolution |
 |-------|------------|
 EOF
-    echo "Created progress.md"
-else
-    echo "progress.md already exists, skipping"
-fi
+}
 
-echo ""
-echo "Planning files initialized!"
-echo "Files: task_plan.md, findings.md, progress.md"
+write_analytics_progress() {
+    local date_value="$1"
+    local target="$2"
+    cat > "$target" << EOF
+# Progress Log
+
+## Session: $date_value
+
+### Current Status
+- **Phase:** 1 - Data Discovery
+- **Started:** $date_value
+
+### Actions Taken
+-
+
+### Query Log
+| Query | Result Summary | Interpretation |
+|-------|---------------|----------------|
+
+### Errors
+| Error | Resolution |
+|-------|------------|
+EOF
+}
+
+create_files_in() {
+    local target_dir="$1"
+    local plan_path="$target_dir/task_plan.md"
+    local findings_path="$target_dir/findings.md"
+    local progress_path="$target_dir/progress.md"
+
+    if [ ! -f "$plan_path" ]; then
+        if [ "$TEMPLATE" = "analytics" ] && [ -f "$TEMPLATE_DIR/analytics_task_plan.md" ]; then
+            cp "$TEMPLATE_DIR/analytics_task_plan.md" "$plan_path"
+        else
+            write_default_task_plan "$plan_path"
+        fi
+        echo "Created $plan_path"
+    else
+        echo "$plan_path already exists, skipping"
+    fi
+
+    if [ ! -f "$findings_path" ]; then
+        if [ "$TEMPLATE" = "analytics" ] && [ -f "$TEMPLATE_DIR/analytics_findings.md" ]; then
+            cp "$TEMPLATE_DIR/analytics_findings.md" "$findings_path"
+        else
+            write_default_findings "$findings_path"
+        fi
+        echo "Created $findings_path"
+    else
+        echo "$findings_path already exists, skipping"
+    fi
+
+    if [ ! -f "$progress_path" ]; then
+        if [ "$TEMPLATE" = "analytics" ]; then
+            write_analytics_progress "$DATE" "$progress_path"
+        else
+            write_default_progress "$DATE" "$progress_path"
+        fi
+        echo "Created $progress_path"
+    else
+        echo "$progress_path already exists, skipping"
+    fi
+}
+
+if [ "$SLUG_MODE" -eq 1 ]; then
+    SLUG="$(slugify "$PROJECT_NAME")"
+    if [ -z "$SLUG" ]; then
+        SLUG="untitled-$(short_uuid)"
+    fi
+    BASE_ID="${DATE}-${SLUG}"
+    PLAN_ID="$BASE_ID"
+    PLAN_ROOT="${PWD}/.planning"
+    counter=2
+    while [ -d "${PLAN_ROOT}/${PLAN_ID}" ]; do
+        PLAN_ID="${BASE_ID}-${counter}"
+        counter=$((counter + 1))
+    done
+    PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
+    mkdir -p "$PLAN_DIR"
+
+    echo "Initializing planning files for: ${PROJECT_NAME:-untitled} (template: $TEMPLATE)"
+    echo "PLAN_ID=$PLAN_ID"
+    create_files_in "$PLAN_DIR"
+    printf "%s\n" "$PLAN_ID" > "${PLAN_ROOT}/.active_plan"
+    echo ""
+    echo "Active plan recorded: ${PLAN_ROOT}/.active_plan"
+    echo "Pin this terminal to the plan for parallel sessions:"
+    echo "  export PLAN_ID=$PLAN_ID"
+else
+    PROJECT_NAME="${PROJECT_NAME:-project}"
+    echo "Initializing planning files for: $PROJECT_NAME (template: $TEMPLATE)"
+    create_files_in "$(pwd)"
+    echo ""
+    echo "Planning files initialized!"
+    echo "Files: task_plan.md, findings.md, progress.md"
+fi

.gemini/skills/planning-with-files/scripts/check-complete.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Check if all phases in task_plan.md are complete
 # Always exits 0 — uses stdout for status reporting
 # Used by Stop hook to report task completion status

.gemini/skills/planning-with-files/scripts/init-session.ps1

@@ -1,17 +1,34 @@
 # Initialize planning files for a new session
-# Usage: .\init-session.ps1 [project-name]
+# Usage: .\init-session.ps1 [-Template TYPE] [project-name]
+# Templates: default, analytics
 
 param(
-    [string]$ProjectName = "project"
+    [string]$ProjectName = "project",
+    [string]$Template = "default"
 )
 
 $DATE = Get-Date -Format "yyyy-MM-dd"
 
-Write-Host "Initializing planning files for: $ProjectName"
+# Resolve template directory (skill root is one level up from scripts/)
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$SkillRoot = Split-Path -Parent $ScriptDir
+$TemplateDir = Join-Path $SkillRoot "templates"
+
+Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
+
+# Validate template
+if ($Template -ne "default" -and $Template -ne "analytics") {
+    Write-Host "Unknown template: $Template (available: default, analytics). Using default."
+    $Template = "default"
+}
 
 # Create task_plan.md if it doesn't exist
 if (-not (Test-Path "task_plan.md")) {
-    @"
+    $AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
+    if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
+        Copy-Item $AnalyticsPlan "task_plan.md"
+    } else {
+        @"
 # Task Plan: [Brief Description]
 
 ## Goal
@@ -56,6 +73,7 @@ Phase 1
 | Error | Resolution |
 |-------|------------|
 "@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
+    }
     Write-Host "Created task_plan.md"
 } else {
     Write-Host "task_plan.md already exists, skipping"
@@ -63,7 +81,11 @@ Phase 1
 
 # Create findings.md if it doesn't exist
 if (-not (Test-Path "findings.md")) {
-    @"
+    $AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
+    if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
+        Copy-Item $AnalyticsFindings "findings.md"
+    } else {
+        @"
 # Findings & Decisions
 
 ## Requirements
@@ -83,6 +105,7 @@ if (-not (Test-Path "findings.md")) {
 ## Resources
 -
 "@ | Out-File -FilePath "findings.md" -Encoding UTF8
+    }
     Write-Host "Created findings.md"
 } else {
     Write-Host "findings.md already exists, skipping"
@@ -90,7 +113,29 @@ if (-not (Test-Path "findings.md")) {
 
 # Create progress.md if it doesn't exist
 if (-not (Test-Path "progress.md")) {
-    @"
+    if ($Template -eq "analytics") {
+        @"
+# Progress Log
+
+## Session: $DATE
+
+### Current Status
+- **Phase:** 1 - Data Discovery
+- **Started:** $DATE
+
+### Actions Taken
+-
+
+### Query Log
+| Query | Result Summary | Interpretation |
+|-------|---------------|----------------|
+
+### Errors
+| Error | Resolution |
+|-------|------------|
+"@ | Out-File -FilePath "progress.md" -Encoding UTF8
+    } else {
+        @"
 # Progress Log
 
 ## Session: $DATE
@@ -110,6 +155,7 @@ if (-not (Test-Path "progress.md")) {
 | Error | Resolution |
 |-------|------------|
 "@ | Out-File -FilePath "progress.md" -Encoding UTF8
+    }
     Write-Host "Created progress.md"
 } else {
     Write-Host "progress.md already exists, skipping"

.gemini/skills/planning-with-files/scripts/init-session.sh

@@ -1,17 +1,96 @@
-#!/bin/bash
-# Initialize planning files for a new session
-# Usage: ./init-session.sh [project-name]
+#!/usr/bin/env bash
+# Initialize planning files for a new session.
+#
+# Usage:
+#   ./init-session.sh                              # legacy: root-level task_plan.md, findings.md, progress.md
+#   ./init-session.sh [--template TYPE]            # legacy with template choice
+#   ./init-session.sh "Backend Refactor"           # slug mode: .planning/<date>-backend-refactor/
+#   ./init-session.sh --plan-dir                   # slug mode with auto-generated untitled-<short> name
+#   ./init-session.sh --plan-dir "Quick Spike"     # slug mode, explicit slug
+#
+# Legacy mode (zero positional args, no --plan-dir) preserves v1.x behavior so
+# upgrades stay non-breaking. Slug mode addresses parallel multi-task isolation
+# (issue #148) by writing each plan under .planning/<date>-<slug>/ and pinning
+# .planning/.active_plan so resolve-plan-dir.sh can find it.
 
 set -e
 
-PROJECT_NAME="${1:-project}"
+TEMPLATE="default"
+PROJECT_NAME=""
+USE_PLAN_DIR=0
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --template|-t)
+            TEMPLATE="$2"
+            shift 2
+            ;;
+        --plan-dir)
+            USE_PLAN_DIR=1
+            shift
+            ;;
+        *)
+            if [ -z "$PROJECT_NAME" ]; then
+                PROJECT_NAME="$1"
+            else
+                PROJECT_NAME="$PROJECT_NAME $1"
+            fi
+            shift
+            ;;
+    esac
+done
+
 DATE=$(date +%Y-%m-%d)
 
-echo "Initializing planning files for: $PROJECT_NAME"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SKILL_ROOT="$(dirname "$SCRIPT_DIR")"
+TEMPLATE_DIR="$SKILL_ROOT/templates"
 
-# Create task_plan.md if it doesn't exist
-if [ ! -f "task_plan.md" ]; then
-    cat > task_plan.md << 'EOF'
+if [ "$TEMPLATE" != "default" ] && [ "$TEMPLATE" != "analytics" ]; then
+    echo "Unknown template: $TEMPLATE (available: default, analytics). Using default."
+    TEMPLATE="default"
+fi
+
+# Slug mode triggers when a project name was given OR --plan-dir was passed.
+SLUG_MODE=0
+if [ -n "$PROJECT_NAME" ] || [ "$USE_PLAN_DIR" -eq 1 ]; then
+    SLUG_MODE=1
+fi
+
+slugify() {
+    # Lowercase, non-alphanumerics → '-', collapse repeats, trim leading/trailing '-'
+    printf '%s' "$1" \
+        | tr '[:upper:]' '[:lower:]' \
+        | sed -e 's/[^a-z0-9]/-/g' -e 's/-\{2,\}/-/g' -e 's/^-//' -e 's/-$//' \
+        | cut -c1-40
+}
+
+short_uuid() {
+    # Probe each candidate: command -v alone is not enough on Windows because
+    # App Execution Aliases report presence but exit non-zero when run.
+    _py="${PYTHON_BIN:-}"
+    if [ -z "$_py" ]; then
+        for _c in python3 python py; do
+            if command -v "$_c" >/dev/null 2>&1 && "$_c" -c "import uuid" >/dev/null 2>&1; then
+                _py="$_c"
+                break
+            fi
+        done
+    fi
+    if [ -n "$_py" ]; then
+        "$_py" -c "import uuid; print(uuid.uuid4().hex[:8])"
+        return
+    fi
+    if command -v uuidgen >/dev/null 2>&1; then
+        uuidgen | tr '[:upper:]' '[:lower:]' | tr -d '-' | cut -c1-8
+        return
+    fi
+    # Last-ditch: seconds timestamp as 8 hex chars
+    printf '%08x' "$(date +%s)" | cut -c1-8
+}
+
+write_default_task_plan() {
+    cat > "$1" << 'EOF'
 # Task Plan: [Brief Description]
 
 ## Goal
@@ -56,14 +135,10 @@ Phase 1
 | Error | Resolution |
 |-------|------------|
 EOF
-    echo "Created task_plan.md"
-else
-    echo "task_plan.md already exists, skipping"
-fi
+}
 
-# Create findings.md if it doesn't exist
-if [ ! -f "findings.md" ]; then
-    cat > findings.md << 'EOF'
+write_default_findings() {
+    cat > "$1" << 'EOF'
 # Findings & Decisions
 
 ## Requirements
@@ -83,21 +158,19 @@ if [ ! -f "findings.md" ]; then
 ## Resources
 -
 EOF
-    echo "Created findings.md"
-else
-    echo "findings.md already exists, skipping"
-fi
+}
 
-# Create progress.md if it doesn't exist
-if [ ! -f "progress.md" ]; then
-    cat > progress.md << EOF
+write_default_progress() {
+    local date_value="$1"
+    local target="$2"
+    cat > "$target" << EOF
 # Progress Log
 
-## Session: $DATE
+## Session: $date_value
 
 ### Current Status
 - **Phase:** 1 - Requirements & Discovery
-- **Started:** $DATE
+- **Started:** $date_value
 
 ### Actions Taken
 -
@@ -110,11 +183,102 @@ if [ ! -f "progress.md" ]; then
 | Error | Resolution |
 |-------|------------|
 EOF
-    echo "Created progress.md"
-else
-    echo "progress.md already exists, skipping"
-fi
+}
 
-echo ""
-echo "Planning files initialized!"
-echo "Files: task_plan.md, findings.md, progress.md"
+write_analytics_progress() {
+    local date_value="$1"
+    local target="$2"
+    cat > "$target" << EOF
+# Progress Log
+
+## Session: $date_value
+
+### Current Status
+- **Phase:** 1 - Data Discovery
+- **Started:** $date_value
+
+### Actions Taken
+-
+
+### Query Log
+| Query | Result Summary | Interpretation |
+|-------|---------------|----------------|
+
+### Errors
+| Error | Resolution |
+|-------|------------|
+EOF
+}
+
+create_files_in() {
+    local target_dir="$1"
+    local plan_path="$target_dir/task_plan.md"
+    local findings_path="$target_dir/findings.md"
+    local progress_path="$target_dir/progress.md"
+
+    if [ ! -f "$plan_path" ]; then
+        if [ "$TEMPLATE" = "analytics" ] && [ -f "$TEMPLATE_DIR/analytics_task_plan.md" ]; then
+            cp "$TEMPLATE_DIR/analytics_task_plan.md" "$plan_path"
+        else
+            write_default_task_plan "$plan_path"
+        fi
+        echo "Created $plan_path"
+    else
+        echo "$plan_path already exists, skipping"
+    fi
+
+    if [ ! -f "$findings_path" ]; then
+        if [ "$TEMPLATE" = "analytics" ] && [ -f "$TEMPLATE_DIR/analytics_findings.md" ]; then
+            cp "$TEMPLATE_DIR/analytics_findings.md" "$findings_path"
+        else
+            write_default_findings "$findings_path"
+        fi
+        echo "Created $findings_path"
+    else
+        echo "$findings_path already exists, skipping"
+    fi
+
+    if [ ! -f "$progress_path" ]; then
+        if [ "$TEMPLATE" = "analytics" ]; then
+            write_analytics_progress "$DATE" "$progress_path"
+        else
+            write_default_progress "$DATE" "$progress_path"
+        fi
+        echo "Created $progress_path"
+    else
+        echo "$progress_path already exists, skipping"
+    fi
+}
+
+if [ "$SLUG_MODE" -eq 1 ]; then
+    SLUG="$(slugify "$PROJECT_NAME")"
+    if [ -z "$SLUG" ]; then
+        SLUG="untitled-$(short_uuid)"
+    fi
+    BASE_ID="${DATE}-${SLUG}"
+    PLAN_ID="$BASE_ID"
+    PLAN_ROOT="${PWD}/.planning"
+    counter=2
+    while [ -d "${PLAN_ROOT}/${PLAN_ID}" ]; do
+        PLAN_ID="${BASE_ID}-${counter}"
+        counter=$((counter + 1))
+    done
+    PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
+    mkdir -p "$PLAN_DIR"
+
+    echo "Initializing planning files for: ${PROJECT_NAME:-untitled} (template: $TEMPLATE)"
+    echo "PLAN_ID=$PLAN_ID"
+    create_files_in "$PLAN_DIR"
+    printf "%s\n" "$PLAN_ID" > "${PLAN_ROOT}/.active_plan"
+    echo ""
+    echo "Active plan recorded: ${PLAN_ROOT}/.active_plan"
+    echo "Pin this terminal to the plan for parallel sessions:"
+    echo "  export PLAN_ID=$PLAN_ID"
+else
+    PROJECT_NAME="${PROJECT_NAME:-project}"
+    echo "Initializing planning files for: $PROJECT_NAME (template: $TEMPLATE)"
+    create_files_in "$(pwd)"
+    echo ""
+    echo "Planning files initialized!"
+    echo "Files: task_plan.md, findings.md, progress.md"
+fi

.hermes/skills/planning-with-files/SKILL.md

@@ -2,7 +2,7 @@
 name: planning-with-files
 description: Implements Manus-style file-based planning to organize and track progress on complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Hermes adaptation with minimal notes.
 metadata:
-  version: "2.36.1"
+  version: "2.36.2"
 ---
 
 > Hermes note: lifecycle automation for this skill is provided by the Hermes adapter plugin in `.hermes/plugins/planning-with-files/`.

.mastracode/skills/planning-with-files/SKILL.md

@@ -23,7 +23,7 @@ hooks:
         - type: command
           command: "SD=\"$HOME/.mastracode/skills/planning-with-files/scripts\"; [ -f \"$SD/check-complete.sh\" ] || SD=\".mastracode/skills/planning-with-files/scripts\"; powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -File \"$SD/check-complete.ps1\" 2>/dev/null || sh \"$SD/check-complete.sh\""
 metadata:
-  version: "2.36.1"
+  version: "2.36.2"
 
 ---
 

.opencode/skills/planning-with-files/SKILL.md

@@ -23,7 +23,7 @@ hooks:
         - type: command
           command: "SD=\"${OPENCODE_SKILL_ROOT:-$HOME/.config/opencode/skills/planning-with-files}/scripts\"; powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -File \"$SD/check-complete.ps1\" 2>/dev/null || sh \"$SD/check-complete.sh\""
 metadata:
-  version: "2.36.1"
+  version: "2.36.2"
 
 ---
 

.pi/skills/planning-with-files/scripts/check-complete.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Check if all phases in task_plan.md are complete
 # Always exits 0 — uses stdout for status reporting
 # Used by Stop hook to report task completion status

.pi/skills/planning-with-files/scripts/init-session.ps1

@@ -1,17 +1,34 @@
 # Initialize planning files for a new session
-# Usage: .\init-session.ps1 [project-name]
+# Usage: .\init-session.ps1 [-Template TYPE] [project-name]
+# Templates: default, analytics
 
 param(
-    [string]$ProjectName = "project"
+    [string]$ProjectName = "project",
+    [string]$Template = "default"
 )
 
 $DATE = Get-Date -Format "yyyy-MM-dd"
 
-Write-Host "Initializing planning files for: $ProjectName"
+# Resolve template directory (skill root is one level up from scripts/)
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$SkillRoot = Split-Path -Parent $ScriptDir
+$TemplateDir = Join-Path $SkillRoot "templates"
+
+Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
+
+# Validate template
+if ($Template -ne "default" -and $Template -ne "analytics") {
+    Write-Host "Unknown template: $Template (available: default, analytics). Using default."
+    $Template = "default"
+}
 
 # Create task_plan.md if it doesn't exist
 if (-not (Test-Path "task_plan.md")) {
-    @"
+    $AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
+    if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
+        Copy-Item $AnalyticsPlan "task_plan.md"
+    } else {
+        @"
 # Task Plan: [Brief Description]
 
 ## Goal
@@ -56,6 +73,7 @@ Phase 1
 | Error | Resolution |
 |-------|------------|
 "@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
+    }
     Write-Host "Created task_plan.md"
 } else {
     Write-Host "task_plan.md already exists, skipping"
@@ -63,7 +81,11 @@ Phase 1
 
 # Create findings.md if it doesn't exist
 if (-not (Test-Path "findings.md")) {
-    @"
+    $AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
+    if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
+        Copy-Item $AnalyticsFindings "findings.md"
+    } else {
+        @"
 # Findings & Decisions
 
 ## Requirements
@@ -83,6 +105,7 @@ if (-not (Test-Path "findings.md")) {
 ## Resources
 -
 "@ | Out-File -FilePath "findings.md" -Encoding UTF8
+    }
     Write-Host "Created findings.md"
 } else {
     Write-Host "findings.md already exists, skipping"
@@ -90,7 +113,29 @@ if (-not (Test-Path "findings.md")) {
 
 # Create progress.md if it doesn't exist
 if (-not (Test-Path "progress.md")) {
-    @"
+    if ($Template -eq "analytics") {
+        @"
+# Progress Log
+
+## Session: $DATE
+
+### Current Status
+- **Phase:** 1 - Data Discovery
+- **Started:** $DATE
+
+### Actions Taken
+-
+
+### Query Log
+| Query | Result Summary | Interpretation |
+|-------|---------------|----------------|
+
+### Errors
+| Error | Resolution |
+|-------|------------|
+"@ | Out-File -FilePath "progress.md" -Encoding UTF8
+    } else {
+        @"
 # Progress Log
 
 ## Session: $DATE
@@ -110,6 +155,7 @@ if (-not (Test-Path "progress.md")) {
 | Error | Resolution |
 |-------|------------|
 "@ | Out-File -FilePath "progress.md" -Encoding UTF8
+    }
     Write-Host "Created progress.md"
 } else {
     Write-Host "progress.md already exists, skipping"

.pi/skills/planning-with-files/scripts/init-session.sh

@@ -1,17 +1,96 @@
-#!/bin/bash
-# Initialize planning files for a new session
-# Usage: ./init-session.sh [project-name]
+#!/usr/bin/env bash
+# Initialize planning files for a new session.
+#
+# Usage:
+#   ./init-session.sh                              # legacy: root-level task_plan.md, findings.md, progress.md
+#   ./init-session.sh [--template TYPE]            # legacy with template choice
+#   ./init-session.sh "Backend Refactor"           # slug mode: .planning/<date>-backend-refactor/
+#   ./init-session.sh --plan-dir                   # slug mode with auto-generated untitled-<short> name
+#   ./init-session.sh --plan-dir "Quick Spike"     # slug mode, explicit slug
+#
+# Legacy mode (zero positional args, no --plan-dir) preserves v1.x behavior so
+# upgrades stay non-breaking. Slug mode addresses parallel multi-task isolation
+# (issue #148) by writing each plan under .planning/<date>-<slug>/ and pinning
+# .planning/.active_plan so resolve-plan-dir.sh can find it.
 
 set -e
 
-PROJECT_NAME="${1:-project}"
+TEMPLATE="default"
+PROJECT_NAME=""
+USE_PLAN_DIR=0
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --template|-t)
+            TEMPLATE="$2"
+            shift 2
+            ;;
+        --plan-dir)
+            USE_PLAN_DIR=1
+            shift
+            ;;
+        *)
+            if [ -z "$PROJECT_NAME" ]; then
+                PROJECT_NAME="$1"
+            else
+                PROJECT_NAME="$PROJECT_NAME $1"
+            fi
+            shift
+            ;;
+    esac
+done
+
 DATE=$(date +%Y-%m-%d)
 
-echo "Initializing planning files for: $PROJECT_NAME"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SKILL_ROOT="$(dirname "$SCRIPT_DIR")"
+TEMPLATE_DIR="$SKILL_ROOT/templates"
 
-# Create task_plan.md if it doesn't exist
-if [ ! -f "task_plan.md" ]; then
-    cat > task_plan.md << 'EOF'
+if [ "$TEMPLATE" != "default" ] && [ "$TEMPLATE" != "analytics" ]; then
+    echo "Unknown template: $TEMPLATE (available: default, analytics). Using default."
+    TEMPLATE="default"
+fi
+
+# Slug mode triggers when a project name was given OR --plan-dir was passed.
+SLUG_MODE=0
+if [ -n "$PROJECT_NAME" ] || [ "$USE_PLAN_DIR" -eq 1 ]; then
+    SLUG_MODE=1
+fi
+
+slugify() {
+    # Lowercase, non-alphanumerics → '-', collapse repeats, trim leading/trailing '-'
+    printf '%s' "$1" \
+        | tr '[:upper:]' '[:lower:]' \
+        | sed -e 's/[^a-z0-9]/-/g' -e 's/-\{2,\}/-/g' -e 's/^-//' -e 's/-$//' \
+        | cut -c1-40
+}
+
+short_uuid() {
+    # Probe each candidate: command -v alone is not enough on Windows because
+    # App Execution Aliases report presence but exit non-zero when run.
+    _py="${PYTHON_BIN:-}"
+    if [ -z "$_py" ]; then
+        for _c in python3 python py; do
+            if command -v "$_c" >/dev/null 2>&1 && "$_c" -c "import uuid" >/dev/null 2>&1; then
+                _py="$_c"
+                break
+            fi
+        done
+    fi
+    if [ -n "$_py" ]; then
+        "$_py" -c "import uuid; print(uuid.uuid4().hex[:8])"
+        return
+    fi
+    if command -v uuidgen >/dev/null 2>&1; then
+        uuidgen | tr '[:upper:]' '[:lower:]' | tr -d '-' | cut -c1-8
+        return
+    fi
+    # Last-ditch: seconds timestamp as 8 hex chars
+    printf '%08x' "$(date +%s)" | cut -c1-8
+}
+
+write_default_task_plan() {
+    cat > "$1" << 'EOF'
 # Task Plan: [Brief Description]
 
 ## Goal
@@ -56,14 +135,10 @@ Phase 1
 | Error | Resolution |
 |-------|------------|
 EOF
-    echo "Created task_plan.md"
-else
-    echo "task_plan.md already exists, skipping"
-fi
+}
 
-# Create findings.md if it doesn't exist
-if [ ! -f "findings.md" ]; then
-    cat > findings.md << 'EOF'
+write_default_findings() {
+    cat > "$1" << 'EOF'
 # Findings & Decisions
 
 ## Requirements
@@ -83,21 +158,19 @@ if [ ! -f "findings.md" ]; then
 ## Resources
 -
 EOF
-    echo "Created findings.md"
-else
-    echo "findings.md already exists, skipping"
-fi
+}
 
-# Create progress.md if it doesn't exist
-if [ ! -f "progress.md" ]; then
-    cat > progress.md << EOF
+write_default_progress() {
+    local date_value="$1"
+    local target="$2"
+    cat > "$target" << EOF
 # Progress Log
 
-## Session: $DATE
+## Session: $date_value
 
 ### Current Status
 - **Phase:** 1 - Requirements & Discovery
-- **Started:** $DATE
+- **Started:** $date_value
 
 ### Actions Taken
 -
@@ -110,11 +183,102 @@ if [ ! -f "progress.md" ]; then
 | Error | Resolution |
 |-------|------------|
 EOF
-    echo "Created progress.md"
-else
-    echo "progress.md already exists, skipping"
-fi
+}
 
-echo ""
-echo "Planning files initialized!"
-echo "Files: task_plan.md, findings.md, progress.md"
+write_analytics_progress() {
+    local date_value="$1"
+    local target="$2"
+    cat > "$target" << EOF
+# Progress Log
+
+## Session: $date_value
+
+### Current Status
+- **Phase:** 1 - Data Discovery
+- **Started:** $date_value
+
+### Actions Taken
+-
+
+### Query Log
+| Query | Result Summary | Interpretation |
+|-------|---------------|----------------|
+
+### Errors
+| Error | Resolution |
+|-------|------------|
+EOF
+}
+
+create_files_in() {
+    local target_dir="$1"
+    local plan_path="$target_dir/task_plan.md"
+    local findings_path="$target_dir/findings.md"
+    local progress_path="$target_dir/progress.md"
+
+    if [ ! -f "$plan_path" ]; then
+        if [ "$TEMPLATE" = "analytics" ] && [ -f "$TEMPLATE_DIR/analytics_task_plan.md" ]; then
+            cp "$TEMPLATE_DIR/analytics_task_plan.md" "$plan_path"
+        else
+            write_default_task_plan "$plan_path"
+        fi
+        echo "Created $plan_path"
+    else
+        echo "$plan_path already exists, skipping"
+    fi
+
+    if [ ! -f "$findings_path" ]; then
+        if [ "$TEMPLATE" = "analytics" ] && [ -f "$TEMPLATE_DIR/analytics_findings.md" ]; then
+            cp "$TEMPLATE_DIR/analytics_findings.md" "$findings_path"
+        else
+            write_default_findings "$findings_path"
+        fi
+        echo "Created $findings_path"
+    else
+        echo "$findings_path already exists, skipping"
+    fi
+
+    if [ ! -f "$progress_path" ]; then
+        if [ "$TEMPLATE" = "analytics" ]; then
+            write_analytics_progress "$DATE" "$progress_path"
+        else
+            write_default_progress "$DATE" "$progress_path"
+        fi
+        echo "Created $progress_path"
+    else
+        echo "$progress_path already exists, skipping"
+    fi
+}
+
+if [ "$SLUG_MODE" -eq 1 ]; then
+    SLUG="$(slugify "$PROJECT_NAME")"
+    if [ -z "$SLUG" ]; then
+        SLUG="untitled-$(short_uuid)"
+    fi
+    BASE_ID="${DATE}-${SLUG}"
+    PLAN_ID="$BASE_ID"
+    PLAN_ROOT="${PWD}/.planning"
+    counter=2
+    while [ -d "${PLAN_ROOT}/${PLAN_ID}" ]; do
+        PLAN_ID="${BASE_ID}-${counter}"
+        counter=$((counter + 1))
+    done
+    PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
+    mkdir -p "$PLAN_DIR"
+
+    echo "Initializing planning files for: ${PROJECT_NAME:-untitled} (template: $TEMPLATE)"
+    echo "PLAN_ID=$PLAN_ID"
+    create_files_in "$PLAN_DIR"
+    printf "%s\n" "$PLAN_ID" > "${PLAN_ROOT}/.active_plan"
+    echo ""
+    echo "Active plan recorded: ${PLAN_ROOT}/.active_plan"
+    echo "Pin this terminal to the plan for parallel sessions:"
+    echo "  export PLAN_ID=$PLAN_ID"
+else
+    PROJECT_NAME="${PROJECT_NAME:-project}"
+    echo "Initializing planning files for: $PROJECT_NAME (template: $TEMPLATE)"
+    create_files_in "$(pwd)"
+    echo ""
+    echo "Planning files initialized!"
+    echo "Files: task_plan.md, findings.md, progress.md"
+fi

AGENTS.md

@@ -0,0 +1,152 @@
+# AGENTS.md — planning-with-files agent reference card
+
+This file is the canonical, session-portable reference for how every agent working in this repo must handle commits, releases, version bumps, CHANGELOG entries, and issue/PR communication.
+
+---
+
+## Commit rules
+
+- **Author**: OthmanAdi only. NEVER add `Co-Authored-By:` trailers.
+- **Format**: Conventional Commits — `fix:`, `feat:`, `release:`, `docs:` prefixes.
+- **One squashed commit per release or PR merge.**
+- No `--no-verify`. No force push to master except tag ref updates.
+- Contributors are credited in CHANGELOG `### Thanks` and `CONTRIBUTORS.md`, never in commit trailers.
+
+---
+
+## Release checklist (12 steps)
+
+1. `gh issue view N` and `gh pr view N` — read both in full.
+2. Verify the bug is real: find the exact file/line, grep for the pattern, confirm reporter is correct.
+3. `python -m pytest tests/ -q` — all tests pass before touching anything.
+4. Squash merge: `git fetch origin branch && git merge --squash origin/branch`, then a single commit as OthmanAdi.
+5. CHANGELOG — new version entry at top, `### Fixed`/`### Added`/`### Changed`, sachlich, no em-dashes.
+6. CONTRIBUTORS.md — add reporter/contributor, bump "Total Contributors: N+", update "Last updated" date.
+7. Version bump across all 19 files (see table below).
+8. README — update version badge and add row to releases table.
+9. `git commit`, `git tag vX.Y.Z`, `git push origin master`, `git push origin vX.Y.Z`.
+10. `gh release create vX.Y.Z --title "vX.Y.Z - <short description>" --notes "<release notes>"`.
+11. Post comment on PR and/or issue via `gh issue comment N --body "..."` (run through /humanizer first).
+12. `gh issue close N` if applicable.
+
+---
+
+## Version bump scope
+
+All 19 files must be bumped to the same version string every release.
+
+| File | Notes |
+|------|-------|
+| `skills/planning-with-files/SKILL.md` | Primary English |
+| `skills/planning-with-files-ar/SKILL.md` | Arabic |
+| `skills/planning-with-files-de/SKILL.md` | German |
+| `skills/planning-with-files-es/SKILL.md` | Spanish |
+| `skills/planning-with-files-zh/SKILL.md` | Simplified Chinese |
+| `skills/planning-with-files-zht/SKILL.md` | Traditional Chinese |
+| `.codebuddy/skills/planning-with-files/SKILL.md` | CodeBuddy IDE |
+| `.codex/skills/planning-with-files/SKILL.md` | Codex IDE |
+| `.cursor/skills/planning-with-files/SKILL.md` | Cursor IDE |
+| `.factory/skills/planning-with-files/SKILL.md` | Factory IDE |
+| `.hermes/skills/planning-with-files/SKILL.md` | Hermes adapter |
+| `.kiro/skills/planning-with-files/SKILL.md` | Kiro IDE |
+| `.mastracode/skills/planning-with-files/SKILL.md` | Mastra Code |
+| `.opencode/skills/planning-with-files/SKILL.md` | OpenCode IDE |
+| `.pi/skills/planning-with-files/SKILL.md` | Pi IDE |
+| `clawhub-upload/SKILL.md` | ClawHub marketplace upload |
+| `.claude-plugin/plugin.json` | Plugin manifest |
+| `.claude-plugin/marketplace.json` | Marketplace metadata |
+| `CITATION.cff` | Citation file |
+
+**NOT bumped automatically**: `.continue/`, `.gemini/` — intentionally behind. Do not bump without an explicit scope decision.
+
+---
+
+## CHANGELOG format
+
+```
+## [X.Y.Z] - YYYY-MM-DD
+
+### Fixed
+- Short description of what was wrong and how it was fixed.
+
+### Thanks
+- @handle — what they contributed (issue #N / PR #N)
+```
+
+Rules:
+- Sachlich (matter-of-fact). No em-dashes. No hype.
+- Contributor line: first name or @handle, one sentence, issue/PR reference.
+- Run any prose through /humanizer before publishing anywhere public.
+
+---
+
+## CONTRIBUTORS.md format
+
+```markdown
+### Other Contributors
+
+**[Name](https://github.com/handle)** — [PR #N](link) / [Issue #N](link)
+- What they did (one bullet per contribution)
+- Impact or context
+```
+
+- Update "Total Contributors: N+" count.
+- Update "Last updated: YYYY-MM-DD" date.
+- Scope determines section: "Other Contributors" for single-issue fix, "Major Contributions" for larger work.
+
+---
+
+## Issue/PR comment style
+
+After a fix ships, comment on the issue or PR:
+
+- Address by `@handle`.
+- One sentence: fix confirmed in vX.Y.Z.
+- Specific: what the root cause was, what mechanism changed.
+- If they are now in CONTRIBUTORS.md, say so.
+- Run through /humanizer before posting.
+
+NOT acceptable in any public comment:
+- "Great report!"
+- "Thank you so much!"
+- Em-dashes (do not use — this style)
+- "I'd like to"
+- Performative warmth of any kind
+
+---
+
+## Release notes format (gh release create --notes)
+
+```
+What changed:
+
+- <Bug description> — <what the fix does>
+- <Feature description> — <how it works>
+
+Thanks: @handle for reporting issue #N.
+```
+
+- Start with what changed, not who did it.
+- No em-dashes.
+- Thanks at the bottom.
+
+---
+
+## ClawHub distribution
+
+- ClawHub does NOT auto-sync with GitHub.
+- After every release: manually upload `clawhub-upload/SKILL.md` at clawhub.io.
+- SSL cert on clawhub.io may be expired — proceed through the browser warning.
+- skills.sh / `npx skills`: pulls from GitHub master automatically on next crawl.
+- Anthropic plugin marketplace: requires ClawHub upload to reflect the new version.
+
+---
+
+## Quick reference: what NOT to do
+
+- Do not add Co-Authored-By to any commit.
+- Do not bump .continue or .gemini without explicit instruction.
+- Do not edit `task_plan.md` or `DESIGN.md` directly (user-owned contracts).
+- Do not log subagent returns into `task_plan.md` — use `progress.md`.
+- Do not use em-dashes in any user-facing prose.
+- Do not skip ClawHub upload after a release.

CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.36.2] - 2026-05-01
+
+### Fixed
+
+- **Canonical skill copy missing slug-mode init-session** (PR #149 by @voidborne-d): `skills/planning-with-files/scripts/init-session.sh` and `init-session.ps1` were not updated when slug mode shipped in v2.36.0. Users installing via `npx skills add` or any of the nine IDE folders received the legacy-only v2.0.0 script, silently missing the parallel plan isolation feature. Fixed by syncing the top-level canonical scripts into the skill directory and all IDE mirrors.
+- **Shebang drift in IDE mirror scripts**: `check-complete.sh` in `.codebuddy/`, `.codex/`, `.continue/`, `.factory/`, `.gemini/`, `.pi/` folders still used `#!/bin/bash`. Synced to `#!/usr/bin/env bash` to match the Emin017 fix from v2.35.1.
+- **Analytics template gap in canonical PS1**: `init-session.ps1` in the canonical skill copy lacked the `--template analytics` support added in v2.29.0 by @mvanhorn. Included in this sync.
+
+### Added
+
+- **Regression test** `tests/test_canonical_script_sync.py`: asserts `init-session.{sh,ps1}` and `check-complete.{sh,ps1}` are byte-identical between `scripts/` and `skills/planning-with-files/scripts/`. A second assertion invokes `sync-ide-folders.py --verify` to catch IDE mirror drift in CI. Prevents this class of silent version mismatch from recurring.
+
+### Changed
+
+- Version bumped to 2.36.2 across 14 SKILL.md variants, `plugin.json`, `marketplace.json`, and `CITATION.cff`
+- `CONTRIBUTORS.md` updated: added @voidborne-d (PR #149)
+
+### Thanks
+
+- @voidborne-d for catching the canonical/top-level script drift, providing grep proof, running the sync tool, and adding the regression test that prevents recurrence (PR #149)
+
 ## [2.36.1] - 2026-05-01
 
 ### Security

CITATION.cff

@@ -7,7 +7,7 @@ authors:
   - family-names: Adi
     given-names: Ahmad Othman Ammar
     alias: OthmanAdi
-version: "2.36.1"
+version: "2.36.2"
 date-released: "2026-05-01"
 license: MIT
 url: "https://github.com/OthmanAdi/planning-with-files"

CONTRIBUTORS.md

@@ -234,6 +234,12 @@ Thank you to everyone who reported issues, provided feedback, and helped test fi
 
 And many others who have starred, forked, and shared this project!
 
+- **[@voidborne-d](https://github.com/voidborne-d)** - [PR #149](https://github.com/OthmanAdi/planning-with-files/pull/149)
+  - Caught that `skills/planning-with-files/scripts/init-session.sh` was not updated when slug mode shipped in v2.36.0, meaning users installing via npx or IDE folders silently received the old script
+  - Identified the same gap in the analytics template (v2.29.0) and the shebang drift from v2.35.1 across IDE mirror folders
+  - Synced the canonical skill copy and all IDE mirrors using the existing `sync-ide-folders.py` tool, and added a byte-comparison regression test plus a `--verify` CI assertion to prevent recurrence
+  - **Impact:** v2.36.0 headline feature (parallel plan isolation) now actually reaches users who install via the skill; regression test closes the drift class permanently
+
 ## How to Contribute
 
 We welcome contributions! Here's how you can help:
@@ -252,6 +258,6 @@ If you've contributed and don't see your name here, please open an issue! We wan
 
 ---
 
-**Total Contributors:** 39+ and growing!
+**Total Contributors:** 40+ and growing!
 
 *Last updated: May 1, 2026*

README.md

@@ -13,7 +13,7 @@
 
 [![Skills Playground](https://skillsplayground.com/badges/installs/othmanadi-planning-with-files-planning-with-files.svg)](https://skillsplayground.com/skills/othmanadi-planning-with-files-planning-with-files/)
 [![Downloads](https://skill-history.com/badge/othmanadi/planning-with-files.svg)](https://skill-history.com/othmanadi/planning-with-files)
-[![Version](https://img.shields.io/badge/version-2.36.0-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
+[![Version](https://img.shields.io/badge/version-2.36.2-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Closed Issues](https://img.shields.io/github/issues-closed/OthmanAdi/planning-with-files?color=success)](https://github.com/OthmanAdi/planning-with-files/issues?q=is%3Aissue+is%3Aclosed)
 [![Closed PRs](https://img.shields.io/github/issues-pr-closed/OthmanAdi/planning-with-files?color=success)](https://github.com/OthmanAdi/planning-with-files/pulls?q=is%3Apr+is%3Aclosed)
@@ -67,6 +67,8 @@ See the full list of everyone who made this project better in [CONTRIBUTORS.md](
 
 | Version | Highlights |
 |---------|------------|
+| **v2.36.2** | **Canonical script sync** (PR #149): `skills/planning-with-files/scripts/init-session.sh` was missing slug mode from v2.36.0; now synced with IDE mirrors + regression test. (thanks @voidborne-d!) |
+| **v2.36.1** | **Security hardening**: Stop hook cache search removed, ExecutionPolicy Bypass changed to RemoteSigned, prompt injection delimiters added. (Gen Agent Trust Hub FAIL resolved) |
 | **v2.36.0** | **Parallel plan isolation + Codex session isolation** (closes #146, #148): `init-session.sh` slug mode, `set-active-plan.sh`, `resolve-plan-dir.sh`, all Codex hooks route through resolver, session attachment gating. **Hermes docs** (closes #147): integration notes added to `docs/hermes.md`. 34 new tests. (thanks @githubYiheng, @09ashishkapoor, @shawnli1874!) |
 | **v2.35.1** | **Shebang portability fix**: changed `/bin/bash` to `/usr/bin/env bash` in hook scripts, fixing compatibility on NixOS and other systems where bash is not at `/bin/bash`. (thanks @Emin017!) |
 | **v2.35.0** | **Hermes adapter + NLPM audit hardening**: Hermes platform 17 support (thanks @bailob!), NLPM audit fixed Python PATH resolution, session-catchup injection cap, Pi PowerShell syntax (thanks @xiaolai!) |

skills/planning-with-files-ar/SKILL.md

@@ -23,7 +23,7 @@ hooks:
         - type: command
           command: "powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -Command \"& (Get-ChildItem -Path (Join-Path ~ '.claude/plugins/cache') -Filter check-complete.ps1 -Recurse -EA 0 | Select-Object -First 1).FullName\" 2>/dev/null || sh \"$(ls $HOME/.claude/plugins/cache/*/*/*/scripts/check-complete.sh 2>/dev/null | head -1)\" 2>/dev/null || true"
 metadata:
-  version: "2.36.1"
+  version: "2.36.2"
 ---
 
 # نظام تخطيط الملفات

skills/planning-with-files-de/SKILL.md

@@ -23,7 +23,7 @@ hooks:
         - type: command
           command: "powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -Command \"& (Get-ChildItem -Path (Join-Path ~ '.claude/plugins/cache') -Filter check-complete.ps1 -Recurse -EA 0 | Select-Object -First 1).FullName\" 2>/dev/null || sh \"$(ls $HOME/.claude/plugins/cache/*/*/*/scripts/check-complete.sh 2>/dev/null | head -1)\" 2>/dev/null || true"
 metadata:
-  version: "2.36.1"
+  version: "2.36.2"
 ---
 
 # Dateiplanungssystem

skills/planning-with-files-es/SKILL.md

@@ -23,7 +23,7 @@ hooks:
         - type: command
           command: "powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -Command \"& (Get-ChildItem -Path (Join-Path ~ '.claude/plugins/cache') -Filter check-complete.ps1 -Recurse -EA 0 | Select-Object -First 1).FullName\" 2>/dev/null || sh \"$(ls $HOME/.claude/plugins/cache/*/*/*/scripts/check-complete.sh 2>/dev/null | head -1)\" 2>/dev/null || true"
 metadata:
-  version: "2.36.1"
+  version: "2.36.2"
 ---
 
 # Sistema de Planificación con Archivos

skills/planning-with-files-zh/SKILL.md

@@ -24,7 +24,7 @@ hooks:
           command: "powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -Command \"& (Get-ChildItem -Path (Join-Path ~ '.claude/plugins/cache') -Filter check-complete.ps1 -Recurse -EA 0 | Select-Object -First 1).FullName\" 2>/dev/null || sh \"$(ls $HOME/.claude/plugins/cache/*/*/*/scripts/check-complete.sh 2>/dev/null | head -1)\" 2>/dev/null || true"
 metadata:
 
-  version: "2.36.1"
+  version: "2.36.2"
 
 ---
 

skills/planning-with-files-zht/SKILL.md

@@ -24,7 +24,7 @@ hooks:
           command: "powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -Command \"& (Get-ChildItem -Path (Join-Path ~ '.claude/plugins/cache') -Filter check-complete.ps1 -Recurse -EA 0 | Select-Object -First 1).FullName\" 2>/dev/null || sh \"$(ls $HOME/.claude/plugins/cache/*/*/*/scripts/check-complete.sh 2>/dev/null | head -1)\" 2>/dev/null || true"
 metadata:
 
-  version: "2.36.1"
+  version: "2.36.2"
 
 ---
 

skills/planning-with-files/SKILL.md

@@ -23,7 +23,7 @@ hooks:
         - type: command
           command: "SKILL_PS1=\"${CLAUDE_SKILL_DIR}/scripts/check-complete.ps1\"; SKILL_SH=\"${CLAUDE_SKILL_DIR}/scripts/check-complete.sh\"; KNOWN_PS1=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/check-complete.ps1\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/check-complete.ps1\" 2>/dev/null | head -1); KNOWN_SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/check-complete.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/check-complete.sh\" 2>/dev/null | head -1); TARGET_PS1=\"${SKILL_PS1:-$KNOWN_PS1}\"; TARGET_SH=\"${SKILL_SH:-$KNOWN_SH}\"; if [ -n \"$TARGET_PS1\" ] && [ -f \"$TARGET_PS1\" ]; then powershell.exe -NoProfile -ExecutionPolicy RemoteSigned -File \"$TARGET_PS1\" 2>/dev/null; elif [ -n \"$TARGET_SH\" ] && [ -f \"$TARGET_SH\" ]; then sh \"$TARGET_SH\" 2>/dev/null; fi"
 metadata:
-  version: "2.36.1"
+  version: "2.36.2"
 ---
 
 # Planning with Files

skills/planning-with-files/scripts/init-session.ps1

@@ -1,17 +1,34 @@
 # Initialize planning files for a new session
-# Usage: .\init-session.ps1 [project-name]
+# Usage: .\init-session.ps1 [-Template TYPE] [project-name]
+# Templates: default, analytics
 
 param(
-    [string]$ProjectName = "project"
+    [string]$ProjectName = "project",
+    [string]$Template = "default"
 )
 
 $DATE = Get-Date -Format "yyyy-MM-dd"
 
-Write-Host "Initializing planning files for: $ProjectName"
+# Resolve template directory (skill root is one level up from scripts/)
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$SkillRoot = Split-Path -Parent $ScriptDir
+$TemplateDir = Join-Path $SkillRoot "templates"
+
+Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
+
+# Validate template
+if ($Template -ne "default" -and $Template -ne "analytics") {
+    Write-Host "Unknown template: $Template (available: default, analytics). Using default."
+    $Template = "default"
+}
 
 # Create task_plan.md if it doesn't exist
 if (-not (Test-Path "task_plan.md")) {
-    @"
+    $AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
+    if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
+        Copy-Item $AnalyticsPlan "task_plan.md"
+    } else {
+        @"
 # Task Plan: [Brief Description]
 
 ## Goal
@@ -56,6 +73,7 @@ Phase 1
 | Error | Resolution |
 |-------|------------|
 "@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
+    }
     Write-Host "Created task_plan.md"
 } else {
     Write-Host "task_plan.md already exists, skipping"
@@ -63,7 +81,11 @@ Phase 1
 
 # Create findings.md if it doesn't exist
 if (-not (Test-Path "findings.md")) {
-    @"
+    $AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
+    if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
+        Copy-Item $AnalyticsFindings "findings.md"
+    } else {
+        @"
 # Findings & Decisions
 
 ## Requirements
@@ -83,6 +105,7 @@ if (-not (Test-Path "findings.md")) {
 ## Resources
 -
 "@ | Out-File -FilePath "findings.md" -Encoding UTF8
+    }
     Write-Host "Created findings.md"
 } else {
     Write-Host "findings.md already exists, skipping"
@@ -90,7 +113,29 @@ if (-not (Test-Path "findings.md")) {
 
 # Create progress.md if it doesn't exist
 if (-not (Test-Path "progress.md")) {
-    @"
+    if ($Template -eq "analytics") {
+        @"
+# Progress Log
+
+## Session: $DATE
+
+### Current Status
+- **Phase:** 1 - Data Discovery
+- **Started:** $DATE
+
+### Actions Taken
+-
+
+### Query Log
+| Query | Result Summary | Interpretation |
+|-------|---------------|----------------|
+
+### Errors
+| Error | Resolution |
+|-------|------------|
+"@ | Out-File -FilePath "progress.md" -Encoding UTF8
+    } else {
+        @"
 # Progress Log
 
 ## Session: $DATE
@@ -110,6 +155,7 @@ if (-not (Test-Path "progress.md")) {
 | Error | Resolution |
 |-------|------------|
 "@ | Out-File -FilePath "progress.md" -Encoding UTF8
+    }
     Write-Host "Created progress.md"
 } else {
     Write-Host "progress.md already exists, skipping"

skills/planning-with-files/scripts/init-session.sh

@@ -1,17 +1,96 @@
 #!/usr/bin/env bash
-# Initialize planning files for a new session
-# Usage: ./init-session.sh [project-name]
+# Initialize planning files for a new session.
+#
+# Usage:
+#   ./init-session.sh                              # legacy: root-level task_plan.md, findings.md, progress.md
+#   ./init-session.sh [--template TYPE]            # legacy with template choice
+#   ./init-session.sh "Backend Refactor"           # slug mode: .planning/<date>-backend-refactor/
+#   ./init-session.sh --plan-dir                   # slug mode with auto-generated untitled-<short> name
+#   ./init-session.sh --plan-dir "Quick Spike"     # slug mode, explicit slug
+#
+# Legacy mode (zero positional args, no --plan-dir) preserves v1.x behavior so
+# upgrades stay non-breaking. Slug mode addresses parallel multi-task isolation
+# (issue #148) by writing each plan under .planning/<date>-<slug>/ and pinning
+# .planning/.active_plan so resolve-plan-dir.sh can find it.
 
 set -e
 
-PROJECT_NAME="${1:-project}"
+TEMPLATE="default"
+PROJECT_NAME=""
+USE_PLAN_DIR=0
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --template|-t)
+            TEMPLATE="$2"
+            shift 2
+            ;;
+        --plan-dir)
+            USE_PLAN_DIR=1
+            shift
+            ;;
+        *)
+            if [ -z "$PROJECT_NAME" ]; then
+                PROJECT_NAME="$1"
+            else
+                PROJECT_NAME="$PROJECT_NAME $1"
+            fi
+            shift
+            ;;
+    esac
+done
+
 DATE=$(date +%Y-%m-%d)
 
-echo "Initializing planning files for: $PROJECT_NAME"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SKILL_ROOT="$(dirname "$SCRIPT_DIR")"
+TEMPLATE_DIR="$SKILL_ROOT/templates"
 
-# Create task_plan.md if it doesn't exist
-if [ ! -f "task_plan.md" ]; then
-    cat > task_plan.md << 'EOF'
+if [ "$TEMPLATE" != "default" ] && [ "$TEMPLATE" != "analytics" ]; then
+    echo "Unknown template: $TEMPLATE (available: default, analytics). Using default."
+    TEMPLATE="default"
+fi
+
+# Slug mode triggers when a project name was given OR --plan-dir was passed.
+SLUG_MODE=0
+if [ -n "$PROJECT_NAME" ] || [ "$USE_PLAN_DIR" -eq 1 ]; then
+    SLUG_MODE=1
+fi
+
+slugify() {
+    # Lowercase, non-alphanumerics → '-', collapse repeats, trim leading/trailing '-'
+    printf '%s' "$1" \
+        | tr '[:upper:]' '[:lower:]' \
+        | sed -e 's/[^a-z0-9]/-/g' -e 's/-\{2,\}/-/g' -e 's/^-//' -e 's/-$//' \
+        | cut -c1-40
+}
+
+short_uuid() {
+    # Probe each candidate: command -v alone is not enough on Windows because
+    # App Execution Aliases report presence but exit non-zero when run.
+    _py="${PYTHON_BIN:-}"
+    if [ -z "$_py" ]; then
+        for _c in python3 python py; do
+            if command -v "$_c" >/dev/null 2>&1 && "$_c" -c "import uuid" >/dev/null 2>&1; then
+                _py="$_c"
+                break
+            fi
+        done
+    fi
+    if [ -n "$_py" ]; then
+        "$_py" -c "import uuid; print(uuid.uuid4().hex[:8])"
+        return
+    fi
+    if command -v uuidgen >/dev/null 2>&1; then
+        uuidgen | tr '[:upper:]' '[:lower:]' | tr -d '-' | cut -c1-8
+        return
+    fi
+    # Last-ditch: seconds timestamp as 8 hex chars
+    printf '%08x' "$(date +%s)" | cut -c1-8
+}
+
+write_default_task_plan() {
+    cat > "$1" << 'EOF'
 # Task Plan: [Brief Description]
 
 ## Goal
@@ -56,14 +135,10 @@ Phase 1
 | Error | Resolution |
 |-------|------------|
 EOF
-    echo "Created task_plan.md"
-else
-    echo "task_plan.md already exists, skipping"
-fi
+}
 
-# Create findings.md if it doesn't exist
-if [ ! -f "findings.md" ]; then
-    cat > findings.md << 'EOF'
+write_default_findings() {
+    cat > "$1" << 'EOF'
 # Findings & Decisions
 
 ## Requirements
@@ -83,21 +158,19 @@ if [ ! -f "findings.md" ]; then
 ## Resources
 -
 EOF
-    echo "Created findings.md"
-else
-    echo "findings.md already exists, skipping"
-fi
+}
 
-# Create progress.md if it doesn't exist
-if [ ! -f "progress.md" ]; then
-    cat > progress.md << EOF
+write_default_progress() {
+    local date_value="$1"
+    local target="$2"
+    cat > "$target" << EOF
 # Progress Log
 
-## Session: $DATE
+## Session: $date_value
 
 ### Current Status
 - **Phase:** 1 - Requirements & Discovery
-- **Started:** $DATE
+- **Started:** $date_value
 
 ### Actions Taken
 -
@@ -110,11 +183,102 @@ if [ ! -f "progress.md" ]; then
 | Error | Resolution |
 |-------|------------|
 EOF
-    echo "Created progress.md"
-else
-    echo "progress.md already exists, skipping"
-fi
+}
 
-echo ""
-echo "Planning files initialized!"
-echo "Files: task_plan.md, findings.md, progress.md"
+write_analytics_progress() {
+    local date_value="$1"
+    local target="$2"
+    cat > "$target" << EOF
+# Progress Log
+
+## Session: $date_value
+
+### Current Status
+- **Phase:** 1 - Data Discovery
+- **Started:** $date_value
+
+### Actions Taken
+-
+
+### Query Log
+| Query | Result Summary | Interpretation |
+|-------|---------------|----------------|
+
+### Errors
+| Error | Resolution |
+|-------|------------|
+EOF
+}
+
+create_files_in() {
+    local target_dir="$1"
+    local plan_path="$target_dir/task_plan.md"
+    local findings_path="$target_dir/findings.md"
+    local progress_path="$target_dir/progress.md"
+
+    if [ ! -f "$plan_path" ]; then
+        if [ "$TEMPLATE" = "analytics" ] && [ -f "$TEMPLATE_DIR/analytics_task_plan.md" ]; then
+            cp "$TEMPLATE_DIR/analytics_task_plan.md" "$plan_path"
+        else
+            write_default_task_plan "$plan_path"
+        fi
+        echo "Created $plan_path"
+    else
+        echo "$plan_path already exists, skipping"
+    fi
+
+    if [ ! -f "$findings_path" ]; then
+        if [ "$TEMPLATE" = "analytics" ] && [ -f "$TEMPLATE_DIR/analytics_findings.md" ]; then
+            cp "$TEMPLATE_DIR/analytics_findings.md" "$findings_path"
+        else
+            write_default_findings "$findings_path"
+        fi
+        echo "Created $findings_path"
+    else
+        echo "$findings_path already exists, skipping"
+    fi
+
+    if [ ! -f "$progress_path" ]; then
+        if [ "$TEMPLATE" = "analytics" ]; then
+            write_analytics_progress "$DATE" "$progress_path"
+        else
+            write_default_progress "$DATE" "$progress_path"
+        fi
+        echo "Created $progress_path"
+    else
+        echo "$progress_path already exists, skipping"
+    fi
+}
+
+if [ "$SLUG_MODE" -eq 1 ]; then
+    SLUG="$(slugify "$PROJECT_NAME")"
+    if [ -z "$SLUG" ]; then
+        SLUG="untitled-$(short_uuid)"
+    fi
+    BASE_ID="${DATE}-${SLUG}"
+    PLAN_ID="$BASE_ID"
+    PLAN_ROOT="${PWD}/.planning"
+    counter=2
+    while [ -d "${PLAN_ROOT}/${PLAN_ID}" ]; do
+        PLAN_ID="${BASE_ID}-${counter}"
+        counter=$((counter + 1))
+    done
+    PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
+    mkdir -p "$PLAN_DIR"
+
+    echo "Initializing planning files for: ${PROJECT_NAME:-untitled} (template: $TEMPLATE)"
+    echo "PLAN_ID=$PLAN_ID"
+    create_files_in "$PLAN_DIR"
+    printf "%s\n" "$PLAN_ID" > "${PLAN_ROOT}/.active_plan"
+    echo ""
+    echo "Active plan recorded: ${PLAN_ROOT}/.active_plan"
+    echo "Pin this terminal to the plan for parallel sessions:"
+    echo "  export PLAN_ID=$PLAN_ID"
+else
+    PROJECT_NAME="${PROJECT_NAME:-project}"
+    echo "Initializing planning files for: $PROJECT_NAME (template: $TEMPLATE)"
+    create_files_in "$(pwd)"
+    echo ""
+    echo "Planning files initialized!"
+    echo "Files: task_plan.md, findings.md, progress.md"
+fi

tests/test_canonical_script_sync.py

@@ -0,0 +1,80 @@
+"""Regression test: keep top-level scripts/ in sync with canonical skills/.../scripts/.
+
+Background — the repo ships two parallel copies of the helper scripts:
+
+  * `scripts/...`                              — top-level (used by tests, CI, dev)
+  * `skills/planning-with-files/scripts/...`   — canonical for the shipped skill;
+                                                 sync-ide-folders.py copies this one
+                                                 into all `.<ide>/skills/.../scripts/`.
+
+Past PRs (analytics template in v2.29.0, slug-mode in v2.36.0) edited only the
+top-level copy and forgot the canonical, so users installing the skill via any IDE
+folder ended up with the previous-version script. This test catches that class of
+drift up front.
+
+It also exercises sync-ide-folders.py --verify so the IDE-folder mirrors stay
+honest after every commit.
+"""
+from __future__ import annotations
+
+import filecmp
+import subprocess
+import sys
+import unittest
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+TOP_SCRIPTS = REPO_ROOT / "scripts"
+SKILL_SCRIPTS = REPO_ROOT / "skills" / "planning-with-files" / "scripts"
+
+# Files that exist in both locations and must stay byte-identical.
+# session-catchup.py is intentionally NOT in this list — the canonical copy carries
+# Codex-specific catchup logic that does not (yet) live at the top level.
+SHARED_SCRIPTS = (
+    "init-session.sh",
+    "init-session.ps1",
+    "check-complete.sh",
+    "check-complete.ps1",
+)
+
+
+class CanonicalScriptSyncTests(unittest.TestCase):
+    def test_shared_scripts_match_canonical_copy(self) -> None:
+        mismatches = []
+        for name in SHARED_SCRIPTS:
+            top = TOP_SCRIPTS / name
+            skill = SKILL_SCRIPTS / name
+            self.assertTrue(top.is_file(), f"missing top-level script: {top}")
+            self.assertTrue(skill.is_file(), f"missing canonical skill script: {skill}")
+            if not filecmp.cmp(top, skill, shallow=False):
+                mismatches.append(name)
+
+        self.assertFalse(
+            mismatches,
+            "Drift detected between scripts/ and skills/planning-with-files/scripts/. "
+            f"Out-of-sync files: {mismatches}. "
+            "Update both copies in the same PR (see CHANGELOG v2.36.0 for the original "
+            "miss). After updating the canonical skill copy, run "
+            "`python scripts/sync-ide-folders.py` to refresh IDE folders.",
+        )
+
+    def test_sync_ide_folders_verify_clean(self) -> None:
+        result = subprocess.run(
+            [sys.executable, str(REPO_ROOT / "scripts" / "sync-ide-folders.py"), "--verify"],
+            cwd=str(REPO_ROOT),
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+        self.assertEqual(
+            0,
+            result.returncode,
+            "sync-ide-folders.py --verify reported drift. "
+            "Run `python scripts/sync-ide-folders.py` from the repo root to fix.\n"
+            f"stdout:\n{result.stdout}\nstderr:\n{result.stderr}",
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()