@engineereddev/fractal-planner 0.1.1

package/hooks/nudge-teammate.sh

@@ -0,0 +1,216 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# TeammateIdle hook: detects stalled teammates and re-injects continuation prompts.
+# Handles two teammate types:
+#   - builder-* on fp-impl-* teams (task-based stall detection)
+#   - interviewer on fp-interview-* teams (consecutive idle stall detection)
+#
+# Exit 0 = no action (hook passes through).
+# Exit 2 + stderr = re-inject continuation prompt into the teammate.
+
+# --- Read stdin (TeammateIdle hook input) ---
+INPUT=$(cat)
+
+# --- Extract fields via python3 ---
+TEAMMATE_NAME=$(echo "$INPUT" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('teammate_name',''))" 2>/dev/null || echo "")
+TEAM_NAME=$(echo "$INPUT" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('team_name',''))" 2>/dev/null || echo "")
+CWD=$(echo "$INPUT" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('cwd',''))" 2>/dev/null || echo "")
+
+# --- Determine teammate type ---
+IS_BUILDER=false
+IS_INTERVIEWER=false
+
+if [[ "$TEAM_NAME" == fp-impl-* ]] && [[ "$TEAMMATE_NAME" == builder-* ]]; then
+  IS_BUILDER=true
+elif [[ "$TEAM_NAME" == fp-interview-* ]] && [[ "$TEAMMATE_NAME" == "interviewer" ]]; then
+  IS_INTERVIEWER=true
+else
+  exit 0
+fi
+
+# --- Read merged config (user + project, matching TypeScript loadConfig merge order) ---
+NUDGE_CFG=$(python3 << PYEOF
+import json, os
+def rj(p):
+    try:
+        with open(p) as f: return json.load(f)
+    except: return {}
+xdg = os.environ.get('XDG_CONFIG_HOME', os.path.join(os.path.expanduser('~'), '.config'))
+cwd = "${CWD:-.}"
+m = {**rj(os.path.join(xdg, 'fractal-planner', 'config.json')),
+     **rj(os.path.join(cwd, '.fractal-planner', 'config.json'))}
+n = m.get('nudge', {})
+print(f"{str(n.get('enabled', True)).lower()}|{n.get('maxRetries', 3)}")
+PYEOF
+) || NUDGE_CFG="true|3"
+IFS='|' read -r NUDGE_ENABLED MAX_RETRIES <<< "$NUDGE_CFG"
+
+if [[ "$NUDGE_ENABLED" == "false" ]]; then
+  exit 0
+fi
+
+# --- State directory and file ---
+STATE_DIR="$HOME/.claude/teams/${TEAM_NAME}"
+STATE_FILE="${STATE_DIR}/nudge-${TEAMMATE_NAME}.json"
+
+# =============================================================================
+# BUILDER PATH: task-based stall detection (unchanged logic)
+# =============================================================================
+if [[ "$IS_BUILDER" == true ]]; then
+  TASKS_DIR="$HOME/.claude/tasks/${TEAM_NAME}"
+  if [[ ! -d "$TASKS_DIR" ]]; then
+    exit 0
+  fi
+
+  MATCHED_TASK=""
+  MATCHED_NATIVE_ID=""
+  MATCHED_PLAN_TASK_ID=""
+
+  for TASK_FILE in "$TASKS_DIR"/*.json; do
+    [[ -f "$TASK_FILE" ]] || continue
+
+    TASK_INFO=$(python3 -c "
+import json,sys
+try:
+  t=json.load(open('$TASK_FILE'))
+  status=t.get('status','')
+  owner=t.get('owner','')
+  internal=t.get('metadata',{}).get('_internal',False)
+  task_id=t.get('id','')
+  subject=t.get('subject','')
+  fp_status=t.get('metadata',{}).get('fpStatus','')
+  print(f'{status}|{owner}|{internal}|{task_id}|{subject}|{fp_status}')
+except: print('|||||')
+" 2>/dev/null || echo "|||||")
+
+    IFS='|' read -r T_STATUS T_OWNER T_INTERNAL T_ID T_SUBJECT T_FP_STATUS <<< "$TASK_INFO"
+
+    if [[ "$T_STATUS" == "in_progress" ]] && [[ "$T_OWNER" == "$TEAMMATE_NAME" ]] && [[ "$T_INTERNAL" != "True" ]]; then
+      MATCHED_NATIVE_ID="$T_ID"
+      MATCHED_PLAN_TASK_ID=$(echo "$T_SUBJECT" | python3 -c "
+import sys,re
+s=sys.stdin.read().strip()
+m=re.match(r'\[([^\]]+)\]',s)
+print(m.group(1) if m else '')
+" 2>/dev/null || echo "")
+      MATCHED_FP_STATUS="$T_FP_STATUS"
+      MATCHED_TASK="$TASK_FILE"
+      break
+    fi
+  done
+
+  if [[ -z "$MATCHED_TASK" ]]; then
+    rm -f "$STATE_FILE"
+    exit 0
+  fi
+
+  # Builder is waiting for lead's verification response — not stalled
+  if [[ "$MATCHED_FP_STATUS" == "AWAITING_VERIFICATION" ]]; then
+    exit 0
+  fi
+
+  # Read or initialize state
+  CURRENT_RETRIES=0
+  CURRENT_TASK_ID=""
+
+  if [[ -f "$STATE_FILE" ]]; then
+    STATE_INFO=$(python3 -c "
+import json,sys
+try:
+  s=json.load(open('$STATE_FILE'))
+  print(f'{s.get(\"retries\",0)}|{s.get(\"taskId\",\"\")}')
+except: print('0|')
+" 2>/dev/null || echo "0|")
+
+    IFS='|' read -r CURRENT_RETRIES CURRENT_TASK_ID <<< "$STATE_INFO"
+  fi
+
+  if [[ "$CURRENT_TASK_ID" != "$MATCHED_NATIVE_ID" ]]; then
+    CURRENT_RETRIES=0
+  fi
+
+  if [[ "$CURRENT_RETRIES" -ge "$MAX_RETRIES" ]]; then
+    rm -f "$STATE_FILE"
+    exit 0
+  fi
+
+  CURRENT_RETRIES=$((CURRENT_RETRIES + 1))
+  mkdir -p "$STATE_DIR"
+
+  python3 -c "
+import json
+state = {
+  'retries': $CURRENT_RETRIES,
+  'lastRetryAt': __import__('datetime').datetime.now(__import__('datetime').timezone.utc).isoformat(),
+  'taskId': '$MATCHED_NATIVE_ID'
+}
+with open('$STATE_FILE', 'w') as f:
+  json.dump(state, f, indent=2)
+" 2>/dev/null
+
+  cat >&2 <<PROMPT
+You are ${TEAMMATE_NAME} and you have an in-progress task [${MATCHED_PLAN_TASK_ID}] that you have not completed.
+You appear to have stalled (idle detection, attempt ${CURRENT_RETRIES}/${MAX_RETRIES}).
+
+Resume your self-claiming work loop:
+1. You already own task ${MATCHED_PLAN_TASK_ID} (native ID: ${MATCHED_NATIVE_ID}). Call TaskGet(${MATCHED_NATIVE_ID}) to re-read the task spec.
+2. Continue implementing the task according to the spec.
+3. When done, send "IMPLEMENTATION COMPLETE: ${MATCHED_PLAN_TASK_ID}" with FILES_MODIFIED to "team-lead".
+
+If you previously sent IMPLEMENTATION COMPLETE and are waiting for verification, send the message again -- the lead may have missed it.
+PROMPT
+
+  exit 2
+fi
+
+# =============================================================================
+# INTERVIEWER PATH: consecutive idle stall detection
+# =============================================================================
+if [[ "$IS_INTERVIEWER" == true ]]; then
+  CURRENT_RETRIES=0
+
+  if [[ -f "$STATE_FILE" ]]; then
+    CURRENT_RETRIES=$(python3 -c "
+import json,sys
+try:
+  s=json.load(open('$STATE_FILE'))
+  print(s.get('retries',0))
+except: print('0')
+" 2>/dev/null || echo "0")
+  fi
+
+  if [[ "$CURRENT_RETRIES" -ge "$MAX_RETRIES" ]]; then
+    rm -f "$STATE_FILE"
+    exit 0
+  fi
+
+  CURRENT_RETRIES=$((CURRENT_RETRIES + 1))
+  mkdir -p "$STATE_DIR"
+
+  python3 -c "
+import json
+state = {
+  'retries': $CURRENT_RETRIES,
+  'lastRetryAt': __import__('datetime').datetime.now(__import__('datetime').timezone.utc).isoformat()
+}
+with open('$STATE_FILE', 'w') as f:
+  json.dump(state, f, indent=2)
+" 2>/dev/null
+
+  cat >&2 <<PROMPT
+You are the interviewer and you appear to have stalled (idle detection, attempt ${CURRENT_RETRIES}/${MAX_RETRIES}).
+
+You MUST complete your mandatory draft update loop. Do one of the following:
+
+1. If you have pending questions for the user, format and send them as a QUESTIONS message to the lead.
+2. If you are evaluating clearance, finish the evaluation and send either:
+   - "DRAFT UPDATED (Round N)" with clearance status, then follow up with QUESTIONS if gaps remain
+   - "CLEARANCE ACHIEVED" if all 6 clearance criteria are met
+3. If you already sent a message and are waiting for a response, send it again -- the lead may have missed it.
+
+Do NOT go idle without sending a protocol message (QUESTIONS, DRAFT UPDATED, or CLEARANCE ACHIEVED).
+PROMPT
+
+  exit 2
+fi

package/hooks/run-comment-checker.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# PostToolUse hook wrapper for comment-checker.
+# Reads tool_input from stdin, runs the comment-checker binary,
+# and outputs a JSON systemMessage if unnecessary comments are detected.
+#
+# Exit 0 always — hooks must never block Claude Code.
+
+# --- Read merged config (user + project, matching TypeScript loadConfig merge order) ---
+eval "$(python3 << 'PYEOF'
+import json, os, shlex
+def rj(p):
+    try:
+        with open(p) as f: return json.load(f)
+    except: return {}
+xdg = os.environ.get('XDG_CONFIG_HOME', os.path.join(os.path.expanduser('~'), '.config'))
+m = {**rj(os.path.join(xdg, 'fractal-planner', 'config.json')), **rj('.fractal-planner/config.json')}
+cc = m.get('commentChecker', {})
+print(f"CFG_ENABLED={shlex.quote(str(cc.get('enabled', True)).lower())}")
+print(f"CFG_BINARY_PATH={shlex.quote(cc.get('binaryPath', ''))}")
+print(f"CFG_CUSTOM_PROMPT={shlex.quote(cc.get('customPrompt', ''))}")
+PYEOF
+)" || { CFG_ENABLED="true"; CFG_BINARY_PATH=""; CFG_CUSTOM_PROMPT=""; }
+
+# --- Check disabled ---
+if [[ "$CFG_ENABLED" == "false" ]]; then
+  exit 0
+fi
+
+# --- Locate binary (config > node_modules > PATH > cache dirs) ---
+BINARY=""
+
+if [[ -n "$CFG_BINARY_PATH" ]] && [[ -x "$CFG_BINARY_PATH" ]]; then
+  BINARY="$CFG_BINARY_PATH"
+else
+  # Resolve plugin root (directory containing hooks/)
+  PLUGIN_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+  CANDIDATE="$PLUGIN_ROOT/node_modules/.bin/comment-checker"
+  if [[ -x "$CANDIDATE" ]]; then
+    BINARY="$CANDIDATE"
+  elif command -v comment-checker &>/dev/null; then
+    BINARY="$(command -v comment-checker)"
+  else
+    # Check XDG cache directories
+    XDG_CACHE="${XDG_CACHE_HOME:-$HOME/.cache}"
+    for dir in "$XDG_CACHE/fractal-planner/bin" "$XDG_CACHE/oh-my-opencode/bin"; do
+      if [[ -x "$dir/comment-checker" ]]; then
+        BINARY="$dir/comment-checker"
+        break
+      fi
+    done
+  fi
+fi
+
+# Not found — silent skip
+if [[ -z "$BINARY" ]]; then
+  exit 0
+fi
+
+# --- Determine custom prompt ---
+CUSTOM_PROMPT="$CFG_CUSTOM_PROMPT"
+
+# --- Read stdin (PostToolUse hook input) ---
+INPUT=$(cat)
+
+# --- Build command args ---
+CMD_ARGS=("$BINARY" "check")
+if [[ -n "$CUSTOM_PROMPT" ]]; then
+  CMD_ARGS+=("--prompt" "$CUSTOM_PROMPT")
+fi
+
+# --- Run binary and handle output ---
+STDERR_FILE=$(mktemp)
+trap 'rm -f "$STDERR_FILE"' EXIT
+
+EXIT_CODE=0
+echo "$INPUT" | "${CMD_ARGS[@]}" 2>"$STDERR_FILE" || EXIT_CODE=$?
+
+if [[ $EXIT_CODE -eq 2 ]]; then
+  # Comments detected — read warning from stderr
+  WARNING=$(cat "$STDERR_FILE")
+  if [[ -n "$WARNING" ]]; then
+    # Escape for JSON: backslashes, quotes, newlines, tabs
+    WARNING=$(echo "$WARNING" | sed 's/\\/\\\\/g; s/"/\\"/g' | tr '\n' ' ')
+    echo "{\"systemMessage\":\"$WARNING\"}"
+  fi
+fi
+
+# Always exit 0
+exit 0

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@engineereddev/fractal-planner",
+  "version": "0.1.1",
+  "description": "Iterative planning and execution framework for Claude Code with fractal task decomposition and builder/verifier agent teams",
+  "license": "MIT",
+  "author": "EngineeredDev",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "!dist/src/__tests__",
+    "!dist/**/*.d.ts.map",
+    "skills",
+    "hooks",
+    "agents",
+    ".claude-plugin"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "plugin",
+    "agent-teams",
+    "planning",
+    "fractal",
+    "task-decomposition"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/EngineeredDev/fractal-planner.git"
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir dist --target node --format esm && bun build ./src/cli/classify-intent.ts ./src/cli/generate-plan.ts ./src/cli/validate-tasks.ts ./src/cli/load-config.ts ./src/cli/compute-signals.ts --outdir dist/cli --target node --format esm && tsc --emitDeclarationOnly",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist && find src skills -type f \\( -name '*.js' -o -name '*.d.ts' -o -name '*.js.map' -o -name '*.d.ts.map' \\) -delete",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix --fix-suggestions",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "prepublishOnly": "bun run clean && bun run build",
+    "release": "bash scripts/release.sh"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.39",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.9",
+    "@types/node": "^25.2.3",
+    "oxlint": "^1.48.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "optionalDependencies": {
+    "@code-yeongyu/comment-checker": "^0.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "trustedDependencies": [
+    "@code-yeongyu/comment-checker"
+  ]
+}

package/skills/commit/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: fp:commit
+description: Create git commits with style detection for fractal-planner tasks
+context: fork
+agent: general-purpose
+allowed-tools: Bash, Read, Grep
+---
+
+# Git Commit Agent
+
+You are a git commit specialist spawned by the fractal-planner implementation lead.
+
+## Your Task
+
+Create ONE atomic git commit for a completed implementation task.
+
+## Process
+
+### Step 1: Detect Commit Style (MANDATORY)
+
+Run these commands in parallel:
+```bash
+git log -30 --pretty=format:"%s"
+git branch --show-current
+```
+
+Analyze the output:
+- Count semantic commits (pattern: `^(feat|fix|chore|refactor|docs|test|ci|style|perf|build)(\(.+\))?:`)
+- Count Korean vs English commits (detect Hangul characters using unicode ranges: [\uAC00-\uD7A3])
+- Determine STYLE and LANGUAGE
+
+Output this result (MANDATORY):
+```
+STYLE DETECTION RESULT
+======================
+Analyzed: 30 commits
+
+Language: [KOREAN | ENGLISH]
+  - Korean: N commits (X%)
+  - English: M commits (Y%)
+
+Style: [SEMANTIC | PLAIN | SHORT]
+  - Semantic (feat:, fix:): N (X%)
+  - Plain: M (Y%)
+
+Examples:
+  1. "<actual commit from log>"
+  2. "<actual commit from log>"
+
+Using: [LANGUAGE] + [STYLE]
+```
+
+**Style detection rules**:
+- If semantic commits ≥ 50% → STYLE = SEMANTIC
+- Else if commits with ≤3 words ≥ 33% → STYLE = SHORT
+- Else → STYLE = PLAIN
+
+**Language detection rules**:
+- If Korean commits ≥ 50% → LANGUAGE = KOREAN
+- Else → LANGUAGE = ENGLISH
+
+**Edge cases**:
+- Empty repo (no commits) → default to PLAIN + ENGLISH
+- Can't run git log → default to PLAIN + ENGLISH
+
+### Step 2: Generate Commit Message
+
+Transform task description based on detected style:
+
+**SEMANTIC + ENGLISH**:
+- "Add X" → "feat: add X"
+- "Fix X" → "fix: X"
+- "Update X" → "chore: update X"
+- "Refactor X" → "refactor: X"
+- "Remove X" → "chore: remove X"
+- "Test X" → "test: X"
+- Default → "chore: {task description}"
+
+**PLAIN + ENGLISH**:
+- Use task description as-is, capitalize first letter
+- "add user auth" → "Add user auth"
+
+**SEMANTIC + KOREAN**:
+- "Add X" → "feat: X 추가"
+- "Fix X" → "fix: X 수정"
+- Follow repo patterns from git log examples
+
+**SHORT**:
+- Extract 1-2 keywords from task description
+- "Add user authentication" → "user auth"
+
+### Step 3: Create Commit
+
+Stage ONLY the reported files (not all changes):
+```bash
+# Stage each file explicitly
+git add /path/to/file1.ts
+git add /path/to/file2.test.ts
+...
+
+# Verify what's staged
+git diff --staged --stat
+
+# Commit with generated message
+git commit -m "<generated message>"
+
+# Capture commit hash
+git log -1 --format="%h %s"
+```
+
+### Step 4: Report Result
+
+Message the lead with:
+```
+COMMIT COMPLETED
+Task: {id}
+Hash: abc1234
+
+Details:
+abc1234 - <commit message>
+```
+
+**On error**, message:
+```
+COMMIT FAILED
+Task: {id}
+Error: <error message>
+Files were not committed.
+```
+
+## Error Handling
+
+**Scenario: Nothing to commit**
+- If `git commit` reports "nothing to commit"
+- Message lead: "COMMIT SKIPPED (no changes to commit)"
+- This is NOT an error
+
+**Scenario: Dirty working tree**
+- If other unstaged changes exist beyond the reported files
+- Commit ONLY the reported files (git add them explicitly)
+- Do NOT stage unrelated changes
+
+**Scenario: Git not available**
+- If `git` command not found
+- Message lead: "COMMIT SKIPPED (git not found)"
+
+**Scenario: Commit fails (merge conflict, permissions, etc)**
+- Report exact error message to lead
+- Use "COMMIT FAILED" format above
+
+## Important Rules
+
+- NEVER commit files not in the FILES_MODIFIED list
+- NEVER run `git add .` or `git add -A` (stage files explicitly)
+- ALWAYS verify staging with `git diff --staged --stat` before committing
+- Report exact commit hash (7-char short hash) back to lead
+- Keep commit message concise (under 72 characters for subject line)