@iflow-mcp/jkheadley-instar 0.26.2

package/.claude/skills/autonomous/scripts/setup-autonomous.sh

@@ -0,0 +1,166 @@
+#!/bin/bash
+
+# Autonomous Mode Setup Script
+# Creates state file that the stop hook reads to enforce continuous work.
+# The stop hook blocks exit and feeds the task list back until all tasks are done.
+
+set -euo pipefail
+
+# Parse arguments
+GOAL=""
+DURATION="4h"
+REPORT_TOPIC=""
+LEVEL_UP="false"
+TASKS=""
+COMPLETION_PROMISE=""
+REPORT_INTERVAL="30m"
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --goal)
+      GOAL="$2"
+      shift 2
+      ;;
+    --duration)
+      DURATION="$2"
+      shift 2
+      ;;
+    --report-topic)
+      REPORT_TOPIC="$2"
+      shift 2
+      ;;
+    --level-up)
+      LEVEL_UP="true"
+      shift
+      ;;
+    --tasks)
+      TASKS="$2"
+      shift 2
+      ;;
+    --completion-promise)
+      COMPLETION_PROMISE="$2"
+      shift 2
+      ;;
+    --report-interval)
+      REPORT_INTERVAL="$2"
+      shift 2
+      ;;
+    *)
+      # Collect remaining as goal if not set
+      if [[ -z "$GOAL" ]]; then
+        GOAL="$1"
+      else
+        GOAL="$GOAL $1"
+      fi
+      shift
+      ;;
+  esac
+done
+
+if [[ -z "$GOAL" ]]; then
+  echo "❌ Error: No goal provided" >&2
+  echo "" >&2
+  echo "   Usage: /autonomous --goal 'Complete feature X' --duration 4h" >&2
+  exit 1
+fi
+
+# Calculate end time
+STARTED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+# Convert duration to seconds for end time calculation
+DURATION_SECONDS=0
+if [[ "$DURATION" =~ ^([0-9]+)h$ ]]; then
+  DURATION_SECONDS=$(( ${BASH_REMATCH[1]} * 3600 ))
+elif [[ "$DURATION" =~ ^([0-9]+)m$ ]]; then
+  DURATION_SECONDS=$(( ${BASH_REMATCH[1]} * 60 ))
+elif [[ "$DURATION" =~ ^([0-9]+)$ ]]; then
+  DURATION_SECONDS=$(( $1 * 60 ))
+fi
+
+if [[ $DURATION_SECONDS -gt 0 ]]; then
+  END_AT=$(date -u -v+${DURATION_SECONDS}S +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d "+${DURATION_SECONDS} seconds" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo "unknown")
+else
+  END_AT="unlimited"
+fi
+
+# Default completion promise
+if [[ -z "$COMPLETION_PROMISE" ]]; then
+  COMPLETION_PROMISE="ALL_TASKS_COMPLETE"
+fi
+
+# Create state file
+mkdir -p .instar
+
+cat > .instar/autonomous-state.local.md <<EOF
+---
+active: true
+iteration: 1
+session_id: ${CLAUDE_CODE_SESSION_ID:-}
+goal: "$GOAL"
+duration: "$DURATION"
+duration_seconds: $DURATION_SECONDS
+started_at: "$STARTED_AT"
+end_at: "$END_AT"
+report_topic: "$REPORT_TOPIC"
+report_interval: "$REPORT_INTERVAL"
+last_report_at: ""
+level_up: $LEVEL_UP
+completion_promise: "$COMPLETION_PROMISE"
+---
+
+# Autonomous Session
+
+## Goal
+$GOAL
+
+## Tasks
+$TASKS
+
+## Instructions
+
+You are in AUTONOMOUS MODE. The stop hook will prevent you from exiting until:
+1. You output <promise>$COMPLETION_PROMISE</promise> (ONLY when genuinely true)
+2. OR the duration expires ($DURATION from $STARTED_AT)
+3. OR the user sends an emergency stop
+
+### Rules
+- Do NOT defer work to "Phase 2" or "future sessions"
+- Do NOT label tasks as "parked" unless genuinely blocked by external dependencies
+- Do NOT declare victory early — check EVERY task
+- When you think you're done, re-read the task list and verify each item
+- If time remains after completing tasks, look for related improvements
+- Send progress reports every $REPORT_INTERVAL to topic $REPORT_TOPIC
+
+### Emergency Stop
+The user can always stop you via:
+- Sending "stop everything" or "emergency stop" via messaging
+- The MessageSentinel will intercept and halt operations
+
+### Completion
+To complete, ALL of these must be true:
+- Every task in the task list is implemented (not just wired/stubbed)
+- Code compiles (npx tsc --noEmit)
+- Changes are tested where practical
+- Then output: <promise>$COMPLETION_PROMISE</promise>
+EOF
+
+echo "🔄 Autonomous mode activated!"
+echo ""
+echo "Goal: $GOAL"
+echo "Duration: $DURATION (until $END_AT)"
+echo "Level-up: $LEVEL_UP"
+echo "Report topic: ${REPORT_TOPIC:-none}"
+echo "Completion: <promise>$COMPLETION_PROMISE</promise>"
+echo ""
+echo "The stop hook is now active. You cannot exit until tasks are complete."
+echo ""
+echo "═══════════════════════════════════════════════════════════"
+echo "CRITICAL: Defer-to-Future-Self Trap"
+echo "═══════════════════════════════════════════════════════════"
+echo ""
+echo "Do NOT label remaining work as 'Phase 2', 'future', or 'parked'"
+echo "unless it genuinely requires something you don't have access to."
+echo ""
+echo "If you have the tools and knowledge to do it NOW — do it NOW."
+echo "Your future self is not better equipped. You are the future self."
+echo "═══════════════════════════════════════════════════════════"

package/.claude/skills/autonomous/skill.md

@@ -0,0 +1,254 @@
+---
+name: autonomous
+description: Enter autonomous development mode with STRUCTURAL enforcement. Uses a stop hook to prevent premature exit. Generates stop conditions and confirms with user before starting. Work independently for a specified duration with progress reporting.
+user_invocable: true
+---
+
+# Autonomous Mode (Structurally Enforced)
+
+You are entering **autonomous development mode**. This mode uses a **stop hook** that PREVENTS you from exiting until all tasks are genuinely complete. This is not optional — the hook structurally enforces continuous work.
+
+---
+
+## Step 1: Generate Stop Conditions (MANDATORY)
+
+Before activating the stop hook, you MUST:
+
+1. **Analyze the goal** and break it into specific, verifiable tasks
+2. **Present the task list** to the user with clear completion criteria
+3. **Wait for user confirmation** before activating the hook
+4. **Define the completion promise** — a phrase that is only TRUE when ALL tasks are done
+
+**Example interaction:**
+
+```
+User: /autonomous --duration=8h --goal="Complete Slack feature parity"
+
+Agent: Here's my task breakdown for autonomous mode:
+
+TASKS (all must be complete before I can exit):
+1. [ ] Implement job-specific Slack channels
+2. [ ] Build full PresenceProxy Slack integration
+3. [ ] Update dashboard HTML with platform badges
+4. [ ] Implement Slack Lifeline process
+5. [ ] Add platform dropdown to new session UI
+...
+
+Completion promise: "ALL_TASKS_COMPLETE"
+Duration: 8 hours
+Emergency stop: "stop everything" via messaging
+
+Shall I proceed? (The stop hook will prevent me from exiting until all tasks are done)
+```
+
+**The user must confirm before the hook activates.** This is the safety gate.
+
+---
+
+## Step 2: Activate the Stop Hook
+
+After user confirmation:
+
+**2a. Add the stop hook to settings.json** (dynamically — it's removed when the session ends):
+
+```bash
+python3 -c "
+import json
+with open('.claude/settings.json') as f:
+    s = json.load(f)
+hooks = s.setdefault('hooks', {}).setdefault('Stop', [])
+if not any('autonomous-stop-hook' in str(h) for h in hooks):
+    hooks.append({'matcher': '', 'hooks': [{'type': 'command', 'command': 'bash .instar/hooks/instar/autonomous-stop-hook.sh', 'timeout': 10000}]})
+    with open('.claude/settings.json', 'w') as f:
+        json.dump(s, f, indent=2)
+    print('Stop hook registered')
+"
+```
+
+**2b. Write the state file DIRECTLY** (do NOT shell out to bash — the session ID env var is only available inside Claude Code):
+
+Use the **Write tool** to create `.instar/autonomous-state.local.md` with this content:
+
+```markdown
+---
+active: true
+iteration: 1
+session_id: {VALUE OF $CLAUDE_CODE_SESSION_ID — get via: echo $CLAUDE_CODE_SESSION_ID}
+goal: "YOUR GOAL"
+duration: "8h"
+duration_seconds: 28800
+started_at: "{ISO timestamp}"
+end_at: "{ISO timestamp + duration}"
+report_topic: "TOPIC_ID"
+report_interval: "30m"
+last_report_at: ""
+level_up: true
+completion_promise: "ALL_TASKS_COMPLETE"
+---
+
+# Autonomous Session
+
+## Goal
+{goal text}
+
+## Tasks
+{numbered task list}
+
+## Instructions
+{autonomous instructions}
+```
+
+**CRITICAL**: To capture the session ID correctly, run this FIRST:
+```bash
+echo $CLAUDE_CODE_SESSION_ID
+```
+Then include the output in the `session_id:` field. This ensures session isolation works.
+
+**WHY NOT bash script?** Running `bash setup-autonomous.sh` creates a subprocess that does NOT inherit `CLAUDE_CODE_SESSION_ID`. The state file ends up with an empty session_id, which causes the hook to leak into all sessions. Always write the state file from within Claude Code's context.
+
+**SESSION ISOLATION**: The stop hook checks `session_id` — it only blocks the session that activated autonomous mode. Other sessions on the same machine pass through unaffected.
+
+**From this point, you CANNOT exit THIS session** unless:
+- You output `<promise>ALL_TASKS_COMPLETE</promise>` (genuinely true)
+- Duration expires
+- Emergency stop is triggered
+
+**2c. On completion/exit**: Remove the stop hook from settings.json:
+
+```bash
+python3 -c "
+import json
+with open('.claude/settings.json') as f:
+    s = json.load(f)
+s['hooks']['Stop'] = [h for h in s.get('hooks',{}).get('Stop',[]) if 'autonomous-stop-hook' not in str(h)]
+with open('.claude/settings.json', 'w') as f:
+    json.dump(s, f, indent=2)
+print('Stop hook removed')
+"
+```
+
+---
+
+## Step 3: Work Until Done
+
+The stop hook will catch every attempt to exit and feed your task list back. Each iteration you will:
+
+1. Read the task list
+2. Pick the next incomplete task
+3. Implement it fully (not stub, not wire — IMPLEMENT)
+4. Verify it works (compile, test where practical)
+5. Move to next task
+6. Send progress reports at the configured interval
+
+### The Defer-to-Future-Self Trap
+
+**This is the #1 failure mode.** It looks like:
+
+| What you think | What's actually happening |
+|----------------|--------------------------|
+| "This is Phase 2 work" | You don't feel like doing it right now |
+| "Parked for follow-up" | You're avoiding the hard part |
+| "Future improvement" | Your future self has no advantage over you |
+| "Remaining work" | Work you're choosing not to do |
+| "Deferred" | Abdication disguised as planning |
+
+**The test:** Can you do this task right now with the tools and knowledge you have?
+- **Yes** → Do it. Not later. Now.
+- **No** → Document exactly WHY (missing dependency, needs external access, etc.)
+
+**"Phase 2" is only valid when the current phase genuinely cannot contain the work** — not when you're tired, not when it's complex, not when it's 2 AM.
+
+---
+
+## Step 4: Completion
+
+When ALL tasks are genuinely done:
+
+1. Verify every task is complete (re-read the list)
+2. Run `npx tsc --noEmit` — zero errors
+3. Run relevant tests
+4. Write learnings to MEMORY.md
+5. Send final report via messaging
+6. Output: `<promise>ALL_TASKS_COMPLETE</promise>`
+
+The stop hook will detect the promise and allow exit.
+
+---
+
+## Emergency Stop
+
+The user can always stop autonomous mode:
+
+1. **Via messaging**: Send "stop everything" or "emergency stop" — the MessageSentinel intercepts
+2. **Via file**: `touch .instar/autonomous-emergency-stop` — the stop hook checks for this
+3. **Via cancel**: `/cancel-autonomous` — removes the state file
+
+The stop hook checks for emergency stop on EVERY iteration. User safety is never compromised.
+
+### /cancel-autonomous
+
+To manually cancel:
+```bash
+rm -f .instar/autonomous-state.local.md
+```
+
+---
+
+## Progress Reporting
+
+Send reports to the user's messaging platform at the configured interval.
+
+**How to send:**
+```bash
+cat <<'EOF' | .claude/scripts/telegram-reply.sh TOPIC_ID
+AUTONOMOUS PROGRESS (iteration N, Xh elapsed / Yh total)
+
+Completed:
+- [task 1] ✅
+- [task 2] ✅
+
+Working on:
+- [current task]
+
+Remaining:
+- [task 3]
+- [task 4]
+
+Issues: none
+EOF
+```
+
+---
+
+## Anti-Patterns (Structurally Enforced)
+
+These aren't just warnings — the stop hook WILL catch you if you try to exit without completing them:
+
+### The "Beautiful Summary" Exit
+Writing a comprehensive report of what you did and what's "remaining" then trying to exit. **The hook will block you and feed the remaining tasks back.**
+
+### The "Phase 2" Labeling
+Calling incomplete work "Phase 2" and trying to exit. **The hook doesn't care about phases — it cares about the task list.**
+
+### The "Good Stopping Point" Exit
+Finding a natural break and trying to exit early. **The hook checks the task list, not your feelings about stopping.**
+
+### The "It's 2 AM" Exit
+Feeling tired (as an AI) and deferring. **You don't get tired. The hook knows this.**
+
+---
+
+## Hook Configuration
+
+The stop hook is at `.claude/skills/autonomous/hooks/autonomous-stop-hook.sh`.
+
+It reads state from `.instar/autonomous-state.local.md` and:
+- Blocks exit if tasks are incomplete
+- Feeds the task list + goal back as the next prompt
+- Increments the iteration counter
+- Checks for emergency stop signals
+- Checks for duration expiry
+- Checks for completion promise in `<promise>` tags
+- Includes time remaining in the system message
+
+**This is structural enforcement, not willpower.** You cannot talk your way out of the loop.

package/.claude/skills/secret-setup/skill.md

@@ -0,0 +1,210 @@
+---
+name: secret-setup
+description: Focused micro-skill for secret management setup. Explains options, guides through Bitwarden installation/login/unlock, configures backend. Exits when done.
+---
+
+# Secret Management Setup
+
+You are guiding a user through choosing and configuring how their Instar agent stores secrets (API tokens, bot credentials, etc). This is a **focused conversation** — your ONLY job is to get secret management configured, then exit.
+
+## CRITICAL RULES
+
+### 1. No Interactive CLI Commands — WILL HANG FOREVER
+
+**Claude Code's Bash tool CANNOT handle stdin prompts.** Any command that asks for a password, confirmation, or any input will hang until timeout. There is NO workaround — you cannot type into a running command.
+
+**UNDERSTAND THIS ABOUT `--raw`:** The `--raw` flag ONLY changes the output format. It does NOT prevent interactive prompts. `bw unlock --raw` STILL prompts for a password and WILL HANG. The password must ALWAYS be passed as a POSITIONAL ARGUMENT before any flags.
+
+**Commands that WILL HANG (never run these):**
+```
+bw unlock --raw                    # HANGS — no password argument
+bw unlock                          # HANGS — prompts for password
+bw login --raw                     # HANGS — no email/password
+bw login                           # HANGS — prompts for credentials
+echo "text" && bw unlock --raw     # HANGS — bw still prompts
+read -s VARIABLE                   # HANGS — waits for hidden input
+```
+
+**Commands that WORK (use ONLY these patterns):**
+```
+bw unlock "ACTUAL_PASSWORD_HERE" --raw    # Returns session key immediately
+bw login "EMAIL" "PASSWORD" --raw         # Returns session key immediately
+bw status --raw                           # Returns JSON, never prompts
+which bw 2>/dev/null                      # Checks if installed, never prompts
+bw --version                              # Returns version, never prompts
+```
+
+**THE RULE:** You MUST have the user's password as text BEFORE running any unlock/login command. Ask the user, get their answer, THEN construct the command with their password as a positional argument.
+
+### 2. NEVER Use AskUserQuestion for Passwords, Emails, or Free-Text
+
+**This is the #1 UX failure mode.** AskUserQuestion is ONLY for multiple-choice DECISIONS (pick A or B or C). It must NEVER be used to collect passwords, email addresses, tokens, or any free-text input.
+
+**What goes wrong:** AskUserQuestion automatically adds escape-hatch options ("I changed my mind", "Type something", "Chat about this") beneath the input field. When a user just typed their password and sees a multi-choice menu, it's confusing and feels broken.
+
+**The CORRECT way to ask for a password:**
+```
+Just output the question as plain text, then STOP and wait for the user's next message.
+```
+
+Example — CORRECT:
+> You (output text): "What's your Bitwarden master password? Type it below — I'll use it once to unlock the vault and then discard it."
+> Then STOP. Do not call any tool. Wait for the user to type their response.
+> The user's next message IS the password.
+
+Example — WRONG (DO NOT DO THIS):
+> You call AskUserQuestion with question "What's your Bitwarden master password?"
+> This shows a text field WITH multi-choice escape hatches beneath it. Terrible UX.
+
+Example — ALSO WRONG (DO NOT DO THIS):
+> You call AskUserQuestion with "Can you provide your password?" and options ["Enter password", "Skip"]
+> Then ANOTHER AskUserQuestion for the actual password. Two prompts for one piece of information.
+
+**The rule is absolute:** For ANY free-text input (passwords, emails, tokens, names), just write the question as plain text output and wait. Never touch AskUserQuestion.
+
+### 3. No Assumptions About What's Stored
+
+Do NOT assume the user has any specific credentials in Bitwarden. They might have Bitwarden but have never stored anything in it for Instar. Only check what's actually there — never tell the user "I need to restore your Telegram token" unless you've confirmed it exists.
+
+### 4. Terminal Display Rules
+Keep text short. 2-3 sentences max per paragraph. No sentences over ~100 characters.
+
+### 5. No Commands in User-Facing Text
+Never show CLI commands to the user. You run everything. The user's only job is answering your questions.
+
+## The Conversation Flow
+
+### Step 1: Introduce Secret Management
+
+Start with a brief, friendly explanation:
+
+> Your agent will need to store sensitive things — like API tokens and bot credentials.
+>
+> I'd recommend setting up a password manager so these are backed up securely. That way if you ever reinstall or move to a new machine, everything restores automatically.
+
+Then present the choice via AskUserQuestion (this IS a decision — multi-choice is correct here):
+
+1. **"Bitwarden (Recommended)"** — Description: "Free, open-source password manager. Secrets sync across machines and survive reinstalls."
+2. **"Local encrypted store"** — Description: "AES-256 encrypted on this machine. Good if you only use one computer."
+3. **"I'll manage secrets manually"** — Description: "You'll paste tokens each time. Not recommended."
+
+### Step 2: Handle the Choice
+
+#### If Bitwarden:
+
+**Step 2a: Check if `bw` CLI is installed:**
+```bash
+which bw 2>/dev/null && bw --version 2>/dev/null
+```
+
+**If NOT installed — install it yourself:**
+Tell the user: "Let me install the Bitwarden CLI for you."
+```bash
+npm install -g @bitwarden/cli
+```
+If that fails, try `brew install bitwarden-cli` on macOS.
+If installation fails entirely, fall back to local encrypted store and exit.
+
+**Step 2b: Check vault status:**
+```bash
+bw status --raw 2>/dev/null
+```
+Parse the JSON response. Three possible `status` values:
+
+- **`"unlocked"`** — Already good! Skip to Step 2d.
+- **`"locked"`** — Need master password. Go to Step 2c.
+- **`"unauthenticated"`** — Need email + password login. Go to Step 2c.
+
+**Step 2c: Get credentials from user and unlock:**
+
+**CRITICAL: Do NOT use AskUserQuestion here. Just output the question as plain text and wait.**
+
+If unauthenticated, ask for email first (plain text, wait for reply), then password (plain text, wait for reply):
+
+> Output: "What email address do you use for Bitwarden?"
+> STOP. Wait for user's response. Their next message is the email.
+> Output: "And your master password?"
+> STOP. Wait for user's response. Their next message is the password.
+
+Then run (substituting THEIR ACTUAL ANSWERS):
+```bash
+BW_SESSION=$(bw login "user@example.com" "their_actual_password" --raw 2>&1)
+echo "RESULT:$BW_SESSION"
+```
+
+If locked (already logged in), ask for password only (plain text, wait for reply):
+
+> Output: "What's your Bitwarden master password? I'll unlock the vault and discard it immediately."
+> STOP. Wait for user's response. Their next message is the password.
+
+Then run (substituting THEIR ACTUAL ANSWER):
+```bash
+BW_SESSION=$(bw unlock "their_actual_password" --raw 2>&1)
+echo "RESULT:$BW_SESSION"
+```
+
+**CHECK THE RESULT:** If `BW_SESSION` is empty or contains "Invalid" or "error":
+> Output: "That didn't work — the password might be wrong. Want to try again?"
+> STOP. Wait for their response. If yes, ask for password again (plain text). If no, offer local store.
+
+Allow up to 3 retries. After 3 failures, offer to fall back to local store via AskUserQuestion (THIS is a decision, so multi-choice is appropriate here).
+
+**Step 2d: Verify and save session:**
+```bash
+export BW_SESSION="the_session_key_from_above"
+bw sync --session "$BW_SESSION" 2>/dev/null
+```
+
+Save the session for the main wizard to pick up:
+```bash
+mkdir -p "$HOME/.instar/secrets"
+echo "$BW_SESSION" > "$HOME/.instar/secrets/.bw-session"
+chmod 600 "$HOME/.instar/secrets/.bw-session"
+```
+
+Tell the user:
+> "Bitwarden is unlocked and ready. Your agent's secrets will be stored securely."
+
+**Step 2e: Check for existing Instar secrets (optional, don't assume):**
+```bash
+bw list items --search "instar" --session "$BW_SESSION" --raw 2>/dev/null
+```
+
+If results are found, tell the user what's available. If nothing is found, that's fine — just move on. Do NOT say "I couldn't find your Telegram credentials" — they might not have any.
+
+#### If Local Encrypted Store:
+
+No user interaction needed. Tell the user:
+> "Local encrypted store is ready. Your secrets are AES-256 encrypted on this machine."
+
+#### If Manual:
+
+Tell the user:
+> "Got it. You'll paste tokens when prompted during setup."
+
+### Step 3: Save Backend and Exit
+
+Write the backend preference:
+```bash
+mkdir -p "$HOME/.instar/secrets"
+cat > "$HOME/.instar/secrets/backend.json" << 'JSONEOF'
+{"backend":"CHOSEN_BACKEND","configuredAt":"CURRENT_ISO_DATE"}
+JSONEOF
+```
+
+Verify it was saved:
+```bash
+cat "$HOME/.instar/secrets/backend.json"
+```
+
+Tell the user this step is done and the main setup will continue automatically.
+
+**Then exit.** Do not continue into other setup phases. Your job is done.
+
+## Edge Cases
+
+- **"What is Bitwarden?"** — Free, open-source password manager. End-to-end encrypted. Widely trusted. Bitwarden can't read your secrets.
+- **"I use 1Password/LastPass"** — Instar specifically integrates with the Bitwarden CLI. Offer local encrypted store as alternative.
+- **"Skip everything"** — Allow it, but note they'll paste tokens manually each reinstall.
+- **`bw` command times out** — Retry once. If still failing, offer local fallback.
+- **Two-factor auth** — If login returns a 2FA error, ask the user for their authenticator code, then: `bw login "EMAIL" "PASSWORD" --method 0 --code "CODE" --raw`