todos-babysit

Babysit Todos

Periodic scanner for backlog and in-progress todos. Cross-references with GitHub PR status, reviews unhandled items, notifies the user, and auto-implements on approval.

Config Discovery

Resolve todo directory paths and optional Discord config. Define the config helpers first:

# --- solopreneur config helpers (inlined from shared/config.md) ---
# Compute the canonical repo identity used as the key under `.repos` in
# solopreneur.json. Falls back to git toplevel path, then $PWD.
solopreneur_repo_key() {
  local url root
  url=$(git remote get-url origin 2>/dev/null || true)
  if [ -n "$url" ]; then
    # Strip protocol schemes (https/http/ssh/git) and user prefixes (git@)
    # in either order — origin URLs come in many shapes:
    #   https://github.com/owner/repo.git
    #   http://github.com/owner/repo.git
    #   ssh://git@github.com/owner/repo.git
    #   git://github.com/owner/repo.git
    #   git@github.com:owner/repo.git
    url="${url#https://}"; url="${url#http://}"
    url="${url#ssh://}";   url="${url#git://}"
    url="${url#git@}"
    url="${url%.git}"
    # Replace the first `:` with `/` — the scp-style `git@host:owner/repo`
    # form. Bash `${var/pattern/replacement}` parses the second `/` as the
    # delimiter; the chars after it (`/` here) are the replacement, so this
    # produces a single slash, not double. (Tested.)
    url="${url/://}"
    printf '%s\n' "$url"
    return
  fi
  root=$(git rev-parse --show-toplevel 2>/dev/null || true)
  if [ -n "$root" ]; then
    printf '%s\n' "$root"
    return
  fi
  printf '%s\n' "$PWD"
}

# Read a feature subtree from solopreneur.json with the 5-layer cascade:
# 1. primary .repos[<repo-key>].<feature>
# 2. primary .default.<feature>
# 3. fallback .repos[<repo-key>].<feature>
# 4. fallback .default.<feature>
# 5. legacy top-level .<feature> (primary then fallback)
# First non-null wins. Each layer is checked inline (no nested helper
# function — bash function declarations are global, even nested ones, and
# would pollute the user's shell namespace).
read_solopreneur_config() {
  local key="\$1"
  local primary="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/solopreneur.json"
  local fallback="$HOME/.claude/solopreneur.json"
  local repo_key; repo_key=$(solopreneur_repo_key)
  local out

  # Layer 1: primary .repos[<repo-key>].<feature>
  if [ -f "$primary" ]; then
    out=$(jq -r --arg rk "$repo_key" --arg fk "$key" '.repos[$rk][$fk] | values' "$primary" 2>/dev/null)
    if [ -n "$out" ]; then printf '%s\n' "$out"; return; fi
    # Layer 2: primary .default.<feature>
    out=$(jq -r --arg fk "$key" '.default[$fk] | values' "$primary" 2>/dev/null)
    if [ -n "$out" ]; then printf '%s\n' "$out"; return; fi
  fi

  # Layers 3 + 4: fallback file, only if different from primary
  if [ "$primary" != "$fallback" ] && [ -f "$fallback" ]; then
    out=$(jq -r --arg rk "$repo_key" --arg fk "$key" '.repos[$rk][$fk] | values' "$fallback" 2>/dev/null)
    if [ -n "$out" ]; then printf '%s\n' "$out"; return; fi
    out=$(jq -r --arg fk "$key" '.default[$fk] | values' "$fallback" 2>/dev/null)
    if [ -n "$out" ]; then printf '%s\n' "$out"; return; fi
  fi

  # Layer 5: legacy top-level — primary then fallback
  if [ -f "$primary" ]; then
    out=$(jq -r --arg fk "$key" '.[$fk] | values' "$primary" 2>/dev/null)
    if [ -n "$out" ]; then printf '%s\n' "$out"; return; fi
  fi
  if [ "$primary" != "$fallback" ] && [ -f "$fallback" ]; then
    out=$(jq -r --arg fk "$key" '.[$fk] | values' "$fallback" 2>/dev/null)
    if [ -n "$out" ]; then printf '%s\n' "$out"; return; fi
  fi
}

# Write a feature subtree to .default.<key> in the primary file.
# Sibling keys are preserved (atomic read-modify-write).
# Usage: write_solopreneur_config greenlight '{fallback_order:["codex-bot","codex-cli"]}'
write_solopreneur_config() {
  local key="\$1"
  local value_expr="\$2"
  local primary="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/solopreneur.json"
  local tmp existing
  mkdir -p "$(dirname "$primary")"
  tmp=$(mktemp "${primary}.XXXXXX")
  existing=$(cat "$primary" 2>/dev/null); [ -z "$existing" ] && existing='{}'
  printf '%s\n' "$existing" \
    | jq --arg fk "$key" --argjson v "$(jq -n "$value_expr")" \
        '.default = ((.default // {}) | .[$fk] = $v)' \
    > "$tmp" || { rm -f "$tmp"; return 1; }
  mv "$tmp" "$primary"
}

# Write a feature subtree to .repos[<repo-key>].<key> in the primary file.
# Sibling repos AND sibling features within the same repo are preserved.
# Usage: write_solopreneur_repo_config preview '{path:"docs/preview"}'
write_solopreneur_repo_config() {
  local key="\$1"
  local value_expr="\$2"
  local primary="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/solopreneur.json"
  local repo_key; repo_key=$(solopreneur_repo_key)
  local tmp existing
  mkdir -p "$(dirname "$primary")"
  tmp=$(mktemp "${primary}.XXXXXX")
  existing=$(cat "$primary" 2>/dev/null); [ -z "$existing" ] && existing='{}'
  printf '%s\n' "$existing" \
    | jq --arg rk "$repo_key" --arg fk "$key" --argjson v "$(jq -n "$value_expr")" \
        '.repos = ((.repos // {}) | .[$rk] = ((.[$rk] // {}) | .[$fk] = $v))' \
    > "$tmp" || { rm -f "$tmp"; return 1; }
  mv "$tmp" "$primary"
}
# --- end solopreneur config helpers ---

1. Check plugin config:

   read_solopreneur_config todos
   read_solopreneur_config discord
   

2. If no todos config — run the same directory discovery as /todos-cleanup: scan project for todo directories, confirm with user, save to config.

3. Discord availability — auto-detect, no user prompt needed:

   # Check for Discord bot token
   if [ -f ~/.claude/channels/discord/.env ]; then
     source ~/.claude/channels/discord/.env
   fi
   
   # Also check plugin config for custom token path
   DISCORD_CFG=$(read_solopreneur_config discord)
   TOKEN_PATH=$(echo "${DISCORD_CFG:-{}}" | jq -r '.token_path // empty')
   if [ -n "$TOKEN_PATH" ] && [ -f "$TOKEN_PATH" ]; then
     source "$TOKEN_PATH"
   fi
   
   DISCORD_AVAILABLE=${DISCORD_BOT_TOKEN:+true}
   

   • Token found + discord.channel_id and discord.guild_id in config → use Discord
   • Token found but no channel/guild config → Discord available but not configured, ask user for channel ID on first run, save to config
   • No token → fallback to terminal output (all notifications print inline)

   Discord config format in ${CLAUDE_CONFIG_DIR:-~/.claude}/solopreneur.json:

   {
     "discord": {
       "channel_id": "123456789",
       "guild_id": "987654321",
       "token_path": "~/.claude/channels/discord/.env"
     }
   }
   

Notification Layer

All notifications go through a consistent interface. The skill decides the backend based on config discovery:

In terminal mode, after presenting all reviews, prompt the user for each item:

[todo-title]: go / later / done / skip?

Operating Modes

Babysit runs in one of two modes, detected automatically:

Auto mode safety principle: only take actions that are safe to do without human judgment. Anything that requires a judgment call → notify and stop.

Main Flow

Phase 1: Pull & Scan

1. git pull --rebase to get latest
2. List all .md files in both $BACKLOG and $DOING
3. Tag each item with its source directory (backlog or doing)
4. Fetch PR status:

   gh pr list --state open --json number,title,headRefName,url
   gh pr list --state closed --json number,title,headRefName,url,mergedAt --limit 20
   

   Filter closed PRs to last 2 days only (compare mergedAt).

Phase 2: Status Comparison

For each todo file, extract keywords from the filename (strip date prefix 2026-03-15- and type prefix feature-request- / bug-), then match against PR titles and branch names.

Classification rules differ by source directory:

$BACKLOG items

Detecting unchanged:

• Discord mode: todo's thread exists and has no user reply after the last bot message
• Terminal mode: skip detection (always re-present)

$DOING items

Key difference: $DOING items never get needs_review (they're already approved for work). A doing item with no PR is stale — possible causes: PR closed without merge, item manually moved, or branch deleted.

Phase 3: Confirmation Checkpoint

After classification, present a summary table. Behavior depends on operating mode.

Summary table (same for both modes):

📊 **Scan Results** ({YYYY-MM-DD HH:MM})

### Backlog ({N} items)
| Todo | Status | PR | Proposed Action |
|------|--------|----|-----------------|
| add-export.md | needs_review | — | Review |
| fix-sync.md | in_progress | #42 | Move to doing + maintain worktree |
| update-ui.md | merged | #38 | Move to done + cleanup |

### Doing ({N} items)
| Todo | Status | PR | Proposed Action |
|------|--------|----|-----------------|
| auth-flow.md | in_progress | #45 | Maintain worktree (rebase) |
| dark-mode.md | merged | #40 | Move to done + cleanup |
| old-feature.md | stale | — | ⚠️ No PR found |

Interactive mode: Post/print the table, then wait for user confirmation:

• yes / go → proceed with all proposed actions
• Override specific items (e.g., "skip add-export, move old-feature to done")
• stop → abort the scan
• Stale items: user picks per item (move to backlog / done / keep)

Auto mode: Post/print the table as a notification (no wait). Then auto-proceed with safe actions only:

• merged → auto-move to $DONE + cleanup
• in_progress → auto-maintain worktree
• needs_review → auto-review
• stale → notify only, do not move (requires human judgment)

Phase 4: Housekeeping

Execute non-review actions confirmed in Phase 3:

1. Merged items (both backlog and doing):

   • Clean up worktree if it exists:

     git worktree remove .worktrees/{slug} --force
     

   • Delete local branch:

     git branch -d {branch-name}
     

   • Move todo file to $DONE

2. In-progress backlog items → move to $DOING

3. In-progress items (both sources) — maintain worktrees:

   • Check for existing worktree:

     git worktree list | grep {branch-name}
     

   • Has worktree → rebase from main:

     cd .worktrees/{slug} && git fetch origin main && git rebase origin/main
     

   • No worktree → create one:

     git worktree add .worktrees/{slug} {branch-name}
     

   • Conflict handling:
     • Simple (< 3 files, clear resolution) → auto-resolve
     • Complex → notify user with conflict file list, wait for instructions
   • Push after successful rebase: git push --force-with-lease

4. Stale items → execute per user's instruction from Phase 3

Commit all file moves:

git add -A todos/
git commit -m "chore: babysit — move completed/stale todos"
git push

Phase 5: Review

For each needs_review backlog todo, invoke /todos-review {file-path}.

Extract from results: Destructiveness, Value, Effort, completion %, recommendation, and Readiness (Auto or Needs Discussion).

If many needs_review items (>10), prioritize:

1. High value + low destructiveness
2. Bug-type items
3. Remaining by date

Phase 6: Readiness Gate

After review, classify each reviewed todo by readiness:

Auto mode implementation flow: For Auto-ready items, proceed directly to the Implementation Flow (below). If /greenlight fails to resolve all issues → stop, leave the PR open, and notify the user. Do not retry or force-merge.

Interactive mode: Present the readiness assessment alongside the review results. User decides whether to go for each item regardless of readiness rating.

Phase 7: Notify

Discord mode

Find existing threads:

TOKEN="$DISCORD_BOT_TOKEN"
DISCORD_CFG=$(read_solopreneur_config discord)
CHANNEL_ID=$(echo "${DISCORD_CFG:-{}}" | jq -r '.channel_id // empty')
GUILD_ID=$(echo "${DISCORD_CFG:-{}}" | jq -r '.guild_id // empty')

# Active threads
curl -s "https://discord.com/api/v10/guilds/$GUILD_ID/threads/active" \
  -H "Authorization: Bot $TOKEN" | \
  jq -r ".threads[] | select(.parent_id==\"$CHANNEL_ID\") | \"\(.id)\t\(.name)\""

# Archived threads
curl -s "https://discord.com/api/v10/channels/$CHANNEL_ID/threads/archived/public" \
  -H "Authorization: Bot $TOKEN" | \
  jq -r '.threads[] | "\(.id)\t\(.name)"'

Match threads by keyword overlap with todo title. Create new threads only for unmatched todos.

Thread content (new review):

📋 **{todo title}**

| Dimension | Rating |
|-----------|--------|
| Destructiveness | {Low/Medium/High} |
| Value | {Low/Medium/High} |
| Effort | {S/M/L} |
| Completion | {N}% |
| Readiness | {Auto / Needs Discussion} |

**Recommendation**: {summary from todos-review}

---
Reply: `go` — implement / `later` — defer / `done` — mark complete

Status update (existing thread, state changed):

🔄 Status update: found matching PR #{number} ({open/merged})
{PR URL}

Skip notification if thread exists and no status change (avoid noise).

Digest (main channel, after all phases complete):

📊 **Babysit Report** ({YYYY-MM-DD HH:MM})

Scanned: {N} backlog + {M} doing
✅ Completed (merged PR): {n} — moved to done
🔄 In progress (open PR): {n} — worktrees maintained
🆕 New reviews: {n}
⚠️ Stale (doing, no PR): {n}
⏸️ Unchanged: {n}

Terminal mode

Print the same information inline. After all reviews, prompt for each item:

--- {todo title} ---
[review summary table]
Recommendation: {summary}

Action? (go / later / done / skip)

Phase 8: Process User Responses

After moving files:

git add -A todos/
git commit -m "chore: move {filename} to {done|later}/"
git push

Implementation Flow

When user approves a todo with go:

Step 1: Plan

Based on review results and todo content, create an implementation plan.

Step 2: Tech Vetting

Invoke /tech-vetting to verify the plan against platform best practices. Report Tech Vetting results to the user — wait for confirmation before proceeding.

Step 3: Create Worktree & Implement

Check for existing worktree/PR:

# Check open PRs
gh pr list --state open --json headRefName,number | \
  jq '.[] | select(.headRefName | contains("{slug}"))'

# Check existing worktrees
git worktree list | grep {slug}

# Create worktree
git worktree add .worktrees/{slug} -b feature/{slug}

Enter the worktree using EnterWorktree, implement the feature, then:

git add -A && git commit -m "feat: {description}"
git push -u origin feature/{slug}
gh pr create --title "{short description}" --body "Implements {todo filename}"

Step 4: Review Loop

Invoke /greenlight on the PR. This runs the full review pipeline:

• Phase 1: Internal review (/simplify, /specialist-review, /review, code review skills)
• Phase 2: Consolidate and fix
• Phase 3: External reviewer loop — activity-detected active bots (Codex bot, and the Gemini bot when active on the repo), Codex CLI, and CodeRabbit as a passive reviewer

In auto mode, invoke it as /greenlight unattended so reviewer exhaustion fails fast (logs and returns non-zero) instead of blocking on the wizard — the auto-mode fail-safe below then leaves the PR and notifies.

Step 5: Wrap Up

After /greenlight completes:

1. ExitWorktree to return to main repo
2. Move todo: $BACKLOG → $DOING
3. Notify user with final status:

   ✅ Implementation complete!
   PR: {url}
   Review: {passed/pending}
   Next: awaiting merge
   

Important Notes

• Two operating modes: Interactive (confirm before acting) vs Auto (safe actions only)
• Readiness gate: Only bug fixes with S effort, low destructiveness, and clear spec can be auto-implemented — everything else requires human approval
• Auto mode fail-safe: If /greenlight can't resolve issues, stop and leave the PR for the user — never force-merge or retry indefinitely
• Worktree isolation: Each todo works in an isolated worktree for parallel development
• Scans both directories: $BACKLOG for new items, $DOING for PR tracking and cleanup
• Auto-cleanup: Merged PR worktrees and local branches are cleaned up
• Noise avoidance: Previously reviewed, unchanged todos are not re-notified
• Conflict escalation: Simple conflicts auto-resolved, complex ones escalated to user
• Tech Vetting gate: Implementation plan must pass tech-vetting; in interactive mode wait for user confirmation