1#!/usr/bin/env bash
2# Initialize planning files for a new session.
3#
4# Usage:
5#   ./init-session.sh                              # legacy: root-level task_plan.md, findings.md, progress.md
6#   ./init-session.sh [--template TYPE]            # legacy with template choice
7#   ./init-session.sh "Backend Refactor"           # slug mode: .planning/<date>-backend-refactor/
8#   ./init-session.sh --plan-dir                   # slug mode with auto-generated untitled-<short> name
9#   ./init-session.sh --plan-dir "Quick Spike"     # slug mode, explicit slug
10#
11# Legacy mode (zero positional args, no --plan-dir) preserves v1.x behavior so
12# upgrades stay non-breaking. Slug mode addresses parallel multi-task isolation
13# (issue #148) by writing each plan under .planning/<date>-<slug>/ and pinning
14# .planning/.active_plan so resolve-plan-dir.sh can find it.
15 
16set -e
17 
18TEMPLATE="default"
19PROJECT_NAME=""
20USE_PLAN_DIR=0
21 
22while [[ $# -gt 0 ]]; do
23    case "$1" in
24        --template|-t)
25            TEMPLATE="$2"
26            shift 2
27            ;;
28        --plan-dir)
29            USE_PLAN_DIR=1
30            shift
31            ;;
32        *)
33            if [ -z "$PROJECT_NAME" ]; then
34                PROJECT_NAME="$1"
35            else
36                PROJECT_NAME="$PROJECT_NAME $1"
37            fi
38            shift
39            ;;
40    esac
41done
42 
43DATE=$(date +%Y-%m-%d)
44 
45SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
46SKILL_ROOT="$(dirname "$SCRIPT_DIR")"
47TEMPLATE_DIR="$SKILL_ROOT/templates"
48 
49if [ "$TEMPLATE" != "default" ] && [ "$TEMPLATE" != "analytics" ]; then
50    echo "Unknown template: $TEMPLATE (available: default, analytics). Using default."
51    TEMPLATE="default"
52fi
53 
54# Slug mode triggers when a project name was given OR --plan-dir was passed.
55SLUG_MODE=0
56if [ -n "$PROJECT_NAME" ] || [ "$USE_PLAN_DIR" -eq 1 ]; then
57    SLUG_MODE=1
58fi
59 
60slugify() {
61    # Lowercase, non-alphanumerics → '-', collapse repeats, trim leading/trailing '-'
62    printf '%s' "$1" \
63        | tr '[:upper:]' '[:lower:]' \
64        | sed -e 's/[^a-z0-9]/-/g' -e 's/-\{2,\}/-/g' -e 's/^-//' -e 's/-$//' \
65        | cut -c1-40
66}
67 
68short_uuid() {
69    # Probe each candidate: command -v alone is not enough on Windows because
70    # App Execution Aliases report presence but exit non-zero when run.
71    _py="${PYTHON_BIN:-}"
72    if [ -z "$_py" ]; then
73        for _c in python3 python py; do
74            if command -v "$_c" >/dev/null 2>&1 && "$_c" -c "import uuid" >/dev/null 2>&1; then
75                _py="$_c"
76                break
77            fi
78        done
79    fi
80    if [ -n "$_py" ]; then
81        "$_py" -c "import uuid; print(uuid.uuid4().hex[:8])"
82        return
83    fi
84    if command -v uuidgen >/dev/null 2>&1; then
85        uuidgen | tr '[:upper:]' '[:lower:]' | tr -d '-' | cut -c1-8
86        return
87    fi
88    # Last-ditch: seconds timestamp as 8 hex chars
89    printf '%08x' "$(date +%s)" | cut -c1-8
90}
91 
92write_default_task_plan() {
93    cat > "$1" << 'EOF'
94# Task Plan: [Brief Description]
95 
96## Goal
97[One sentence describing the end state]
98 
99## Current Phase
100Phase 1
101 
102## Phases
103 
104### Phase 1: Requirements & Discovery
105- [ ] Understand user intent
106- [ ] Identify constraints
107- [ ] Document in findings.md
108- **Status:** in_progress
109 
110### Phase 2: Planning & Structure
111- [ ] Define approach
112- [ ] Create project structure
113- **Status:** pending
114 
115### Phase 3: Implementation
116- [ ] Execute the plan
117- [ ] Write to files before executing
118- **Status:** pending
119 
120### Phase 4: Testing & Verification
121- [ ] Verify requirements met
122- [ ] Document test results
123- **Status:** pending
124 
125### Phase 5: Delivery
126- [ ] Review outputs
127- [ ] Deliver to user
128- **Status:** pending
129 
130## Decisions Made
131| Decision | Rationale |
132|----------|-----------|
133 
134## Errors Encountered
135| Error | Resolution |
136|-------|------------|
137EOF
138}
139 
140write_default_findings() {
141    cat > "$1" << 'EOF'
142# Findings & Decisions
143 
144## Requirements
145-
146 
147## Research Findings
148-
149 
150## Technical Decisions
151| Decision | Rationale |
152|----------|-----------|
153 
154## Issues Encountered
155| Issue | Resolution |
156|-------|------------|
157 
158## Resources
159-
160EOF
161}
162 
163write_default_progress() {
164    local date_value="$1"
165    local target="$2"
166    cat > "$target" << EOF
167# Progress Log
168 
169## Session: $date_value
170 
171### Current Status
172- **Phase:** 1 - Requirements & Discovery
173- **Started:** $date_value
174 
175### Actions Taken
176-
177 
178### Test Results
179| Test | Expected | Actual | Status |
180|------|----------|--------|--------|
181 
182### Errors
183| Error | Resolution |
184|-------|------------|
185EOF
186}
187 
188write_analytics_progress() {
189    local date_value="$1"
190    local target="$2"
191    cat > "$target" << EOF
192# Progress Log
193 
194## Session: $date_value
195 
196### Current Status
197- **Phase:** 1 - Data Discovery
198- **Started:** $date_value
199 
200### Actions Taken
201-
202 
203### Query Log
204| Query | Result Summary | Interpretation |
205|-------|---------------|----------------|
206 
207### Errors
208| Error | Resolution |
209|-------|------------|
210EOF
211}
212 
213create_files_in() {
214    local target_dir="$1"
215    local plan_path="$target_dir/task_plan.md"
216    local findings_path="$target_dir/findings.md"
217    local progress_path="$target_dir/progress.md"
218 
219    if [ ! -f "$plan_path" ]; then
220        if [ "$TEMPLATE" = "analytics" ] && [ -f "$TEMPLATE_DIR/analytics_task_plan.md" ]; then
221            cp "$TEMPLATE_DIR/analytics_task_plan.md" "$plan_path"
222        else
223            write_default_task_plan "$plan_path"
224        fi
225        echo "Created $plan_path"
226    else
227        echo "$plan_path already exists, skipping"
228    fi
229 
230    if [ ! -f "$findings_path" ]; then
231        if [ "$TEMPLATE" = "analytics" ] && [ -f "$TEMPLATE_DIR/analytics_findings.md" ]; then
232            cp "$TEMPLATE_DIR/analytics_findings.md" "$findings_path"
233        else
234            write_default_findings "$findings_path"
235        fi
236        echo "Created $findings_path"
237    else
238        echo "$findings_path already exists, skipping"
239    fi
240 
241    if [ ! -f "$progress_path" ]; then
242        if [ "$TEMPLATE" = "analytics" ]; then
243            write_analytics_progress "$DATE" "$progress_path"
244        else
245            write_default_progress "$DATE" "$progress_path"
246        fi
247        echo "Created $progress_path"
248    else
249        echo "$progress_path already exists, skipping"
250    fi
251}
252 
253if [ "$SLUG_MODE" -eq 1 ]; then
254    SLUG="$(slugify "$PROJECT_NAME")"
255    if [ -z "$SLUG" ]; then
256        SLUG="untitled-$(short_uuid)"
257    fi
258    BASE_ID="${DATE}-${SLUG}"
259    PLAN_ID="$BASE_ID"
260    PLAN_ROOT="${PWD}/.planning"
261    counter=2
262    while [ -d "${PLAN_ROOT}/${PLAN_ID}" ]; do
263        PLAN_ID="${BASE_ID}-${counter}"
264        counter=$((counter + 1))
265    done
266    PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
267    mkdir -p "$PLAN_DIR"
268 
269    echo "Initializing planning files for: ${PROJECT_NAME:-untitled} (template: $TEMPLATE)"
270    echo "PLAN_ID=$PLAN_ID"
271    create_files_in "$PLAN_DIR"
272    printf "%s\n" "$PLAN_ID" > "${PLAN_ROOT}/.active_plan"
273    echo ""
274    echo "Active plan recorded: ${PLAN_ROOT}/.active_plan"
275    echo "Pin this terminal to the plan for parallel sessions:"
276    echo "  export PLAN_ID=$PLAN_ID"
277else
278    PROJECT_NAME="${PROJECT_NAME:-project}"
279    echo "Initializing planning files for: $PROJECT_NAME (template: $TEMPLATE)"
280    create_files_in "$(pwd)"
281    echo ""
282    echo "Planning files initialized!"
283    echo "Files: task_plan.md, findings.md, progress.md"
284fi
285