monomind 1.16.5 → 1.16.7

package/packages/@monomind/cli/.claude/skills/mastermind/finish.md

@@ -0,0 +1,251 @@
+---
+name: mastermind-finish
+description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work — guides completion of development work by presenting structured options for merge, PR, or cleanup
+---
+
+# Finishing a Development Branch
+
+## Overview
+
+Guide completion of development work by presenting clear options and handling the chosen workflow.
+
+**Core principle:** Verify tests → Detect environment → Present options → Execute choice → Clean up.
+
+**Announce at start:** "I'm using the mastermind:finish skill to complete this work."
+
+## The Process
+
+### Step 1: Verify Tests
+
+**Before presenting options, verify tests pass:**
+
+```bash
+# Run project's test suite
+npm test / cargo test / pytest / go test ./...
+```
+
+**If tests fail:**
+```
+Tests failing (<N> failures). Must fix before completing:
+
+[Show failures]
+
+Cannot proceed with merge/PR until tests pass.
+```
+
+Stop. Don't proceed to Step 2.
+
+**If tests pass:** Continue to Step 2.
+
+### Step 2: Detect Environment
+
+**Determine workspace state before presenting options:**
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+```
+
+This determines which menu to show and how cleanup works:
+
+| State | Menu | Cleanup |
+|-------|------|---------|
+| `GIT_DIR == GIT_COMMON` (normal repo) | Standard 4 options | No worktree to clean up |
+| `GIT_DIR != GIT_COMMON`, named branch | Standard 4 options | Provenance-based (see Step 6) |
+| `GIT_DIR != GIT_COMMON`, detached HEAD | Reduced 3 options (no merge) | No cleanup (externally managed) |
+
+### Step 3: Determine Base Branch
+
+```bash
+# Try common base branches
+git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
+```
+
+Or ask: "This branch split from main — is that correct?"
+
+### Step 4: Present Options
+
+**Normal repo and named-branch worktree — present exactly these 4 options:**
+
+```
+Implementation complete. What would you like to do?
+
+1. Merge back to <base-branch> locally
+2. Push and create a Pull Request
+3. Keep the branch as-is (I'll handle it later)
+4. Discard this work
+
+Which option?
+```
+
+**Detached HEAD — present exactly these 3 options:**
+
+```
+Implementation complete. You're on a detached HEAD (externally managed workspace).
+
+1. Push as new branch and create a Pull Request
+2. Keep as-is (I'll handle it later)
+3. Discard this work
+
+Which option?
+```
+
+**Don't add explanation** — keep options concise.
+
+### Step 5: Execute Choice
+
+#### Option 1: Merge Locally
+
+```bash
+# Get main repo root for CWD safety
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
+
+# Merge first — verify success before removing anything
+git checkout <base-branch>
+git pull
+git merge <feature-branch>
+
+# Verify tests on merged result
+<test command>
+
+# Only after merge succeeds: cleanup worktree (Step 6), then delete branch
+```
+
+Then: Cleanup worktree (Step 6), then delete branch:
+
+```bash
+git branch -d <feature-branch>
+```
+
+#### Option 2: Push and Create PR
+
+```bash
+# Push branch
+git push -u origin <feature-branch>
+
+# Create PR
+gh pr create --title "<title>" --body "$(cat <<'EOF'
+## Summary
+<2-3 bullets of what changed>
+
+## Test Plan
+- [ ] <verification steps>
+EOF
+)"
+```
+
+**Do NOT clean up worktree** — user needs it alive to iterate on PR feedback.
+
+#### Option 3: Keep As-Is
+
+Report: "Keeping branch <name>. Worktree preserved at <path>."
+
+**Don't cleanup worktree.**
+
+#### Option 4: Discard
+
+**Confirm first:**
+```
+This will permanently delete:
+- Branch <name>
+- All commits: <commit-list>
+- Worktree at <path>
+
+Type 'discard' to confirm.
+```
+
+Wait for exact confirmation.
+
+If confirmed:
+```bash
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
+```
+
+Then: Cleanup worktree (Step 6), then force-delete branch:
+```bash
+git branch -D <feature-branch>
+```
+
+### Step 6: Cleanup Workspace
+
+**Only runs for Options 1 and 4.** Options 2 and 3 always preserve the worktree.
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+WORKTREE_PATH=$(git rev-parse --show-toplevel)
+```
+
+**If `GIT_DIR == GIT_COMMON`:** Normal repo, no worktree to clean up. Done.
+
+**If worktree path is under `.worktrees/`, `worktrees/`, or `~/.config/monomind/worktrees/`:** Mastermind created this worktree — we own cleanup.
+
+```bash
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
+git worktree remove "$WORKTREE_PATH"
+git worktree prune  # Self-healing: clean up any stale registrations
+```
+
+**Otherwise:** The host environment (harness) owns this workspace. Do NOT remove it. If your platform provides a workspace-exit tool, use it. Otherwise, leave the workspace in place.
+
+## Quick Reference
+
+| Option | Merge | Push | Keep Worktree | Cleanup Branch |
+|--------|-------|------|---------------|----------------|
+| 1. Merge locally | yes | - | - | yes |
+| 2. Create PR | - | yes | yes | - |
+| 3. Keep as-is | - | - | yes | - |
+| 4. Discard | - | - | - | yes (force) |
+
+## Common Mistakes
+
+**Skipping test verification**
+- **Problem:** Merge broken code, create failing PR
+- **Fix:** Always verify tests before offering options
+
+**Open-ended questions**
+- **Problem:** "What should I do next?" is ambiguous
+- **Fix:** Present exactly 4 structured options (or 3 for detached HEAD)
+
+**Cleaning up worktree for Option 2**
+- **Problem:** Remove worktree user needs for PR iteration
+- **Fix:** Only cleanup for Options 1 and 4
+
+**Deleting branch before removing worktree**
+- **Problem:** `git branch -d` fails because worktree still references the branch
+- **Fix:** Merge first, remove worktree, then delete branch
+
+**Running git worktree remove from inside the worktree**
+- **Problem:** Command fails silently when CWD is inside the worktree being removed
+- **Fix:** Always `cd` to main repo root before `git worktree remove`
+
+**Cleaning up harness-owned worktrees**
+- **Problem:** Removing a worktree the harness created causes phantom state
+- **Fix:** Only clean up worktrees under `.worktrees/`, `worktrees/`, or `~/.config/monomind/worktrees/`
+
+**No confirmation for discard**
+- **Problem:** Accidentally delete work
+- **Fix:** Require typed "discard" confirmation
+
+## Red Flags
+
+**Never:**
+- Proceed with failing tests
+- Merge without verifying tests on result
+- Delete work without confirmation
+- Force-push without explicit request
+- Remove a worktree before confirming merge success
+- Clean up worktrees you didn't create (provenance check)
+- Run `git worktree remove` from inside the worktree
+
+**Always:**
+- Verify tests before offering options
+- Detect environment before presenting menu
+- Present exactly 4 options (or 3 for detached HEAD)
+- Get typed confirmation for Option 4
+- Clean up worktree for Options 1 & 4 only
+- `cd` to main repo root before worktree removal
+- Run `git worktree prune` after removal

package/packages/@monomind/cli/.claude/skills/mastermind/goal-detail.md

@@ -0,0 +1,255 @@
+---
+name: mastermind-goal-detail
+description: Mastermind goal-detail — deep per-goal inspection and management. Show sub-goal tree, linked projects, edit title/status/description/priority, add child goals, and close or reopen a single goal within an org.
+type: domain-skill
+default_mode: auto
+---
+
+# Mastermind Goal Detail
+
+This skill is invoked by `mastermind:goal-detail` or directly via `/mastermind:goal-detail`.
+
+---
+
+## Inputs
+
+- `brain_context`: BRAIN CONTEXT block (injected by command, or loaded below if standalone)
+- `org_name`: org the goal belongs to (required)
+- `goal_id`: goal id/slug (required)
+- `action`: show | tree | projects | edit | add-child | close | reopen
+- `field`: field to edit (title | description | status | priority | parent_id)
+- `value`: new field value (required for edit)
+- `child_title`: title for the new child goal (required for add-child)
+- `child_description`: description for the new child goal (optional)
+- `caller`: command | master
+
+---
+
+## Goal Status Flow
+
+```
+open → in_progress → done
+  └──────────────────┘  (can reopen)
+```
+
+## Priority Levels
+
+`critical` | `high` | `medium` | `low`
+
+---
+
+## Step 0 — Brain Load (standalone only)
+
+If `caller` is not "command", load brain context following _protocol.md Brain Load Procedure with namespace: `ops`.
+
+---
+
+## Step 1 — Load Goal Data
+
+```bash
+orgFile=".monomind/orgs/${org_name}.json"
+[ ! -f "$orgFile" ] && { echo "ERROR: Org '${org_name}' not found."; exit 1; }
+
+goalsFile=".monomind/orgs/${org_name}-goals.json"
+[ ! -f "$goalsFile" ] && { echo "ERROR: No goals file for org '$org_name'. Create goals via /mastermind:goals."; exit 1; }
+
+goalDef=$(jq -r --arg id "$goal_id" '(.goals // [])[] | select(.id == $id or .slug == $id)' "$goalsFile")
+[ -z "$goalDef" ] && { echo "ERROR: Goal '$goal_id' not found in org '$org_name'."; exit 1; }
+
+resolvedId=$(echo "$goalDef" | jq -r '.id')
+projectsFile=".monomind/orgs/${org_name}-projects.json"
+```
+
+---
+
+## Step 2 — Execute Action
+
+### show (default)
+
+```bash
+echo "GOAL DETAIL — $goal_id @ $org_name"
+echo "────────────────────────────────────────────────────────"
+
+echo "$goalDef" | jq -r '
+  "  ID:           \(.id)",
+  "  Title:        \(.title // "(no title)")",
+  "  Status:       \(.status // "open")",
+  "  Priority:     \(.priority // "medium")",
+  "  Parent:       \(.parent_id // "(root goal)")",
+  "  Created:      \(.created_at // "-")",
+  "  Updated:      \(.updated_at // "-")"
+'
+
+# Sub-goals count
+subCount=$(jq --arg pid "$resolvedId" '[(.goals // [])[] | select(.parent_id == $pid)] | length' "$goalsFile" 2>/dev/null || echo 0)
+doneCount=$(jq --arg pid "$resolvedId" '[(.goals // [])[] | select(.parent_id == $pid and .status == "done")] | length' "$goalsFile" 2>/dev/null || echo 0)
+echo "  Sub-goals:    $subCount total, $doneCount done"
+
+# Linked projects
+projCount=$(echo "$goalDef" | jq -r '(.linked_projects // []) | length')
+echo "  Projects:     $projCount linked"
+
+# Description
+desc=$(echo "$goalDef" | jq -r '.description // ""')
+if [ -n "$desc" ]; then
+  echo ""
+  echo "DESCRIPTION"
+  echo "────────────────────────────────────────────────────────"
+  echo "$desc"
+fi
+```
+
+### tree
+
+```bash
+echo "SUB-GOAL TREE — $goal_id"
+echo "────────────────────────────────────────────────────────"
+
+function print_tree() {
+  local pid="$1"
+  local indent="$2"
+  local children
+  children=$(jq -r --arg pid "$pid" '(.goals // [])[] | select(.parent_id == $pid) |
+    [.id, (.status // "open"), (.title // "(no title)")] | @tsv' "$goalsFile" 2>/dev/null)
+  while IFS=$'\t' read -r cid cst ctitle; do
+    [ -z "$cid" ] && continue
+    echo "${indent}[${cst}] ${ctitle} (${cid})"
+    print_tree "$cid" "  ${indent}"
+  done <<< "$children"
+}
+
+# Print root goal
+rootTitle=$(echo "$goalDef" | jq -r '.title // "(no title)"')
+rootStatus=$(echo "$goalDef" | jq -r '.status // "open"')
+echo "[${rootStatus}] ${rootTitle} (${resolvedId})"
+print_tree "$resolvedId" "  "
+```
+
+### projects
+
+```bash
+echo "LINKED PROJECTS — $goal_id"
+echo "────────────────────────────────────────────────────────"
+
+linkedIds=$(echo "$goalDef" | jq -r '(.linked_projects // [])[]')
+if [ -z "$linkedIds" ]; then
+  echo "  No linked projects."
+else
+  while IFS= read -r pid; do
+    [ -z "$pid" ] && continue
+    if [ -f "$projectsFile" ]; then
+      projInfo=$(jq -r --arg id "$pid" '(.projects // [])[] | select(.id == $id) |
+        "  [\(.status // "active")] \(.name // $id) — \(.description // "")"' "$projectsFile" 2>/dev/null)
+      [ -n "$projInfo" ] && echo "$projInfo" || echo "  [$pid] (project not found in projects file)"
+    else
+      echo "  $pid"
+    fi
+  done <<< "$linkedIds"
+fi
+
+echo ""
+echo "Issues referencing this goal:"
+issuesFile=".monomind/orgs/${org_name}-issues.json"
+if [ -f "$issuesFile" ]; then
+  count=$(jq --arg gid "$resolvedId" '[(.issues // [])[] | select(.goal_id == $gid)] | length' "$issuesFile" 2>/dev/null || echo 0)
+  echo "  $count issue(s) linked to this goal."
+fi
+```
+
+### edit
+
+```bash
+[ -z "$field" ] && { echo "ERROR: --field required (title|description|status|priority|parent_id)."; exit 1; }
+[ -z "$value" ] && { echo "ERROR: --value required."; exit 1; }
+
+validFields="title description status priority parent_id"
+echo "$validFields" | tr ' ' '\n' | grep -qx "$field" || {
+  echo "ERROR: Unknown field '$field'. Valid: $validFields"; exit 1
+}
+
+if [ "$field" = "status" ]; then
+  case "$value" in open|in_progress|done|cancelled) : ;; *)
+    echo "ERROR: status must be one of: open, in_progress, done, cancelled"; exit 1 ;;
+  esac
+fi
+if [ "$field" = "priority" ]; then
+  case "$value" in critical|high|medium|low) : ;; *)
+    echo "ERROR: priority must be one of: critical, high, medium, low"; exit 1 ;;
+  esac
+fi
+
+ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+tmp="${goalsFile}.tmp"
+jq --arg id "$resolvedId" --arg field "$field" --arg val "$value" --arg ts "$ts" \
+  '.goals = [(.goals // [])[] | if .id == $id then .[$field] = $val | .updated_at = $ts else . end]' \
+  "$goalsFile" > "$tmp" && mv "$tmp" "$goalsFile"
+
+echo "Goal '$goal_id' updated: $field = $value"
+```
+
+### add-child
+
+```bash
+[ -z "$child_title" ] && { echo "ERROR: --child-title required."; exit 1; }
+
+childId="goal-$(openssl rand -hex 4 2>/dev/null || python3 -c 'import secrets; print(secrets.token_hex(4))')"
+ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+tmp="${goalsFile}.tmp"
+jq --arg id "$childId" \
+   --arg title "$child_title" \
+   --arg desc "${child_description:-}" \
+   --arg pid "$resolvedId" \
+   --arg ts "$ts" \
+  '.goals += [{"id":$id,"title":$title,
+    "description":(if $desc != "" then $desc else null end),
+    "parent_id":$pid,"status":"open","priority":"medium",
+    "linked_projects":[],"created_at":$ts,"updated_at":$ts}]' \
+  "$goalsFile" > "$tmp" && mv "$tmp" "$goalsFile"
+
+echo "Sub-goal created: $childId"
+echo "  Title:  $child_title"
+echo "  Parent: $goal_id"
+```
+
+### close
+
+```bash
+ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+tmp="${goalsFile}.tmp"
+jq --arg id "$resolvedId" --arg ts "$ts" \
+  '.goals = [(.goals // [])[] | if .id == $id then .status = "done" | .updated_at = $ts | .closed_at = $ts else . end]' \
+  "$goalsFile" > "$tmp" && mv "$tmp" "$goalsFile"
+echo "Goal '$goal_id' → done."
+```
+
+### reopen
+
+```bash
+ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+tmp="${goalsFile}.tmp"
+jq --arg id "$resolvedId" --arg ts "$ts" \
+  '.goals = [(.goals // [])[] | if .id == $id then .status = "open" | .updated_at = $ts | .closed_at = null else . end]' \
+  "$goalsFile" > "$tmp" && mv "$tmp" "$goalsFile"
+echo "Goal '$goal_id' → reopened."
+```
+
+---
+
+## Step 3 — Return Output
+
+```yaml
+domain: ops
+status: complete
+action: <action>
+org: <org_name>
+goal_id: <goal_id>
+goal_status: <status>
+sub_goals: <N>
+```
+
+---
+
+## Step 4 — Brain Write (standalone only)
+
+If `caller` is not "command", follow _protocol.md Brain Write Procedure for domain `ops`.

package/packages/@monomind/cli/.claude/skills/mastermind/goals.md

@@ -0,0 +1,149 @@
+---
+name: mastermind-goals
+description: Mastermind goals — define, track, and visualize hierarchical goals for an org. Goals link to tasks, have progress metrics, and form a goal tree.
+type: domain-skill
+default_mode: confirm
+---
+
+# Mastermind Goals
+
+This skill is invoked by `mastermind:goals` or directly via `/mastermind:goals`.
+
+---
+
+## Inputs
+
+- `brain_context`: BRAIN CONTEXT block
+- `org_name`: org whose goals to manage
+- `action`: list | add | update | link | close
+- `goal_title`: title for add
+- `goal_id`: slug for update/link/close
+- `parent_goal`: parent goal slug (for hierarchy)
+- `status`: active | achieved | paused | cancelled
+- `metric`: success metric description (e.g. "100 blog posts published")
+- `caller`: command | master
+
+---
+
+## Step 0 — Brain Load (standalone only)
+
+If `caller` is not "command", load brain context following _protocol.md Brain Load Procedure with namespace: `ops`.
+
+---
+
+## Step 1 — Load Goals State
+
+Goals are stored in `.monomind/orgs/<org_name>-goals.json`. Create if missing:
+
+```bash
+goalsFile=".monomind/orgs/${org_name}-goals.json"
+[ ! -f "$goalsFile" ] && echo '{"goals":[]}' > "$goalsFile"
+```
+
+---
+
+## Step 2 — Execute Action
+
+### list (default)
+
+Render goal tree with progress metrics. Goals without a `parent` are root goals; child goals are indented:
+
+```bash
+jq -r '
+  def tree(gs; pid):
+    gs | map(select(.parent == pid)) | .[] |
+    ("  " * (.depth // 0)) + "[\(.id)] \(.title)  [\(.status // "active")] \(.metric // "")" ,
+    tree(gs; .id);
+  .goals | tree(.; null)
+' "$goalsFile" 2>/dev/null || jq -r '(.goals // [])[] | "[\(.id)] \(.title)  [\(.status // "active")]"' "$goalsFile"
+```
+
+Render as:
+```
+GOALS — org: <org_name>
+──────────────────────────────────────
+[grow-audience] Grow audience to 10k followers  [active]
+  [content-output] Publish 3 posts/week         [active]  metric: 3 posts/week
+    [blog-drafts] 5 draft articles in pipeline  [active]
+[improve-seo] Rank top 10 for target keywords   [active]
+```
+
+### add
+
+```bash
+goal_slug=$(echo "$goal_title" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | tr -s '-')
+tmp="${goalsFile}.tmp"
+jq --arg id "$goal_slug" \
+   --arg title "$goal_title" \
+   --arg parent "${parent_goal:-}" \
+   --arg status "active" \
+   --arg metric "${metric:-}" \
+   --arg created_at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+   '.goals += [{"id":$id,"title":$title,"parent":($parent|if .=="" then null else . end),"status":$status,"metric":$metric,"created_at":$created_at,"tasks":[]}]' \
+   "$goalsFile" > "$tmp" && mv "$tmp" "$goalsFile"
+echo "Goal added: $goal_slug"
+```
+
+Emit `org:goal:created` event to dashboard.
+
+### update
+
+Update goal status or metric:
+
+```bash
+tmp="${goalsFile}.tmp"
+jq --arg id "$goal_id" \
+   --arg status "${status:-}" \
+   --arg metric "${metric:-}" \
+   '.goals = [(.goals // [])[] | if .id == $id then
+     (if $status != "" then .status = $status else . end) |
+     (if $metric != "" then .metric = $metric else . end) |
+     (.updated_at = (now|todate))
+   else . end]' \
+   "$goalsFile" > "$tmp" && mv "$tmp" "$goalsFile"
+```
+
+### link
+
+Link a task id to a goal (append to goal's tasks array):
+
+```bash
+tmp="${goalsFile}.tmp"
+jq --arg id "$goal_id" --arg task "$task_id" \
+   '.goals = [(.goals // [])[] | if .id == $id then .tasks += [$task] else . end]' \
+   "$goalsFile" > "$tmp" && mv "$tmp" "$goalsFile"
+```
+
+### close
+
+Mark goal as achieved and timestamp:
+
+```bash
+tmp="${goalsFile}.tmp"
+jq --arg id "$goal_id" \
+   '.goals = [(.goals // [])[] | if .id == $id then .status = "achieved" | .achieved_at = (now|todate) else . end]' \
+   "$goalsFile" > "$tmp" && mv "$tmp" "$goalsFile"
+```
+
+Emit `org:goal:achieved` event.
+
+---
+
+## Step 3 — Return Output
+
+```yaml
+domain: ops
+status: complete
+action: <action>
+org: <org_name>
+goal_id: <goal_id if applicable>
+goals_file: .monomind/orgs/<org_name>-goals.json
+```
+
+Suggest next: "Link tasks to this goal with /mastermind:tasks link or /mastermind:goals link --goal-id <id> --task-id <card_id>"
+
+---
+
+## Step 4 — Brain Write (standalone only)
+
+If `caller` is not "command", follow _protocol.md Brain Write Procedure for domain `ops`.