monomind 1.16.6 → 1.16.7

package/packages/@monomind/cli/.claude/skills/mastermind/skill-builder.md

@@ -0,0 +1,274 @@
+---
+name: mastermind-skill-builder
+description: Use when creating new mastermind skills, editing existing mastermind skills, or verifying mastermind skills work before deployment
+---
+
+# Writing Mastermind Skills
+
+## Overview
+
+**Writing mastermind skills IS Test-Driven Development applied to process documentation.**
+
+**Mastermind skills live in `.claude/skills/mastermind/` and commands in `.claude/commands/mastermind/`.**
+
+You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).
+
+**Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.
+
+## What is a Mastermind Skill?
+
+A **skill** is a reference guide for proven techniques, patterns, or tools. Skills help future Claude instances find and apply effective approaches.
+
+**Skills are:** Reusable techniques, patterns, tools, reference guides
+
+**Skills are NOT:** Narratives about how you solved a problem once
+
+## TDD Mapping for Skills
+
+| TDD Concept | Skill Creation |
+|-------------|----------------|
+| **Test case** | Pressure scenario with subagent |
+| **Production code** | Skill document (`.md`) |
+| **Test fails (RED)** | Agent violates rule without skill (baseline) |
+| **Test passes (GREEN)** | Agent complies with skill present |
+| **Refactor** | Close loopholes while maintaining compliance |
+| **Write test first** | Run baseline scenario BEFORE writing skill |
+| **Watch it fail** | Document exact rationalizations agent uses |
+| **Minimal code** | Write skill addressing those specific violations |
+| **Watch it pass** | Verify agent now complies |
+| **Refactor cycle** | Find new rationalizations → plug → re-verify |
+
+## When to Create a Skill
+
+**Create when:**
+- Technique wasn't intuitively obvious
+- You'd reference this again across projects
+- Pattern applies broadly (not project-specific)
+- Others would benefit
+
+**Don't create for:**
+- One-off solutions
+- Standard practices well-documented elsewhere
+- Project-specific conventions (put in CLAUDE.md)
+- Mechanical constraints (if it's enforceable with regex/validation, automate it)
+
+## Skill Types
+
+### Technique
+Concrete method with steps to follow
+
+### Pattern
+Way of thinking about problems
+
+### Reference
+API docs, syntax guides, tool documentation
+
+## Directory Structure
+
+```
+.claude/skills/mastermind/
+  skill-name.md              # Main skill (required)
+
+.claude/commands/mastermind/
+  skill-name.md              # Command entry point (required)
+```
+
+**Flat namespace** — all mastermind skills in one searchable namespace.
+
+## Skill File Structure
+
+**Frontmatter (YAML):**
+- Two required fields: `name` and `description` (max 1024 characters total)
+- `name`: Use letters, numbers, and hyphens only (no parentheses, special chars)
+- `description`: Third-person, describes ONLY when to use (NOT what it does)
+  - Start with "Use when..." to focus on triggering conditions
+  - Include specific symptoms, situations, and contexts
+  - **NEVER summarize the skill's process or workflow** (see CSO section)
+  - Keep under 500 characters if possible
+
+```markdown
+---
+name: mastermind-skill-name
+description: Use when [specific triggering conditions and symptoms]
+---
+
+# Skill Name
+
+## Overview
+What is this? Core principle in 1-2 sentences.
+
+## Quick Reference
+Table or bullets for scanning common operations
+
+## The Process / Core Pattern
+Steps, before/after comparisons
+
+## Common Mistakes
+What goes wrong + fixes
+
+## Red Flags
+Never / Always lists
+```
+
+## Command File Structure
+
+Every skill needs a companion command file:
+
+```markdown
+---
+name: mastermind-[name]
+description: [one-line description of when to use]
+---
+
+**First — extract repeat flags:** Follow REPEAT PREAMBLE from `_repeat.md`.
+
+Parse `$ARGUMENTS` for `--auto`, `--confirm`, `--project <name>`, and remaining text.
+
+Load brain context (follow `_protocol.md` Brain Load Procedure).
+
+Default mode: **confirm** (or **auto** for low-risk/fast skills).
+
+---
+
+Invoke `Skill("mastermind:[name]")` passing: brain_context, params, mode.
+
+After skill returns: follow `_protocol.md` Brain Write Procedure.
+
+Invoke `Skill("mastermind:_repeat")` now. Required — do not skip.
+```
+
+## Claude Search Optimization (CSO)
+
+**Critical for discovery:** Future Claude must FIND your skill.
+
+### Description = When to Use, NOT What the Skill Does
+
+The description should ONLY describe triggering conditions. Do NOT summarize the skill's process or workflow in the description.
+
+**Why this matters:** When a description summarizes the workflow, Claude may follow the description instead of reading the full skill content — the skill body becomes documentation Claude skips.
+
+```yaml
+# BAD: Summarizes workflow
+description: Use when finishing branches - runs tests, shows 4 options, handles merge/PR/cleanup
+
+# BAD: Too much process detail
+description: Use for TDD - write test first, watch it fail, write minimal code, refactor
+
+# GOOD: Just triggering conditions
+description: Use when implementation is complete and you need to decide how to integrate the work
+
+# GOOD: Triggering conditions only
+description: Use when receiving code review feedback before implementing suggestions
+```
+
+### Keyword Coverage
+
+Use words Claude would search for:
+- Error messages and symptoms
+- Synonyms (timeout/hang/freeze, cleanup/teardown)
+- Tools: actual commands, library names
+
+### Token Efficiency (Critical)
+
+**Target word counts:**
+- Frequently-loaded skills: under 200 words total
+- Other skills: under 500 words (still be concise)
+
+**Techniques:**
+- Reference other skills instead of repeating content
+- Use cross-references: `**REQUIRED BACKGROUND:** Use Skill("mastermind:X")`
+- One excellent example beats many mediocre ones
+
+### Cross-Referencing Other Skills
+
+```markdown
+# GOOD: Explicit requirement marker
+**REQUIRED SUB-SKILL:** Use Skill("mastermind:worktree")
+**REQUIRED BACKGROUND:** You MUST understand Skill("mastermind:finish")
+
+# BAD: Unclear if required
+See mastermind/worktree.md
+```
+
+## The Iron Law (Same as TDD)
+
+```
+NO SKILL WITHOUT A FAILING TEST FIRST
+```
+
+This applies to NEW skills AND EDITS to existing skills.
+
+Write skill before testing? Delete it. Start over.
+Edit skill without testing? Same violation.
+
+**No exceptions:**
+- Not for "simple additions"
+- Not for "just adding a section"
+- Not for "documentation updates"
+- Delete means delete
+
+## RED-GREEN-REFACTOR for Skills
+
+### RED: Write Failing Test (Baseline)
+
+Run pressure scenario with subagent WITHOUT the skill. Document exact behavior:
+- What choices did they make?
+- What rationalizations did they use (verbatim)?
+- Which pressures triggered violations?
+
+### GREEN: Write Minimal Skill
+
+Write skill that addresses those specific rationalizations. Don't add extra content for hypothetical cases.
+
+Run same scenarios WITH skill. Agent should now comply.
+
+### REFACTOR: Close Loopholes
+
+Agent found new rationalization? Add explicit counter. Re-test until bulletproof.
+
+## Common Rationalizations for Skipping Testing
+
+| Excuse | Reality |
+|--------|---------|
+| "Skill is obviously clear" | Clear to you ≠ clear to other agents. Test it. |
+| "It's just a reference" | References can have gaps. Test retrieval. |
+| "Testing is overkill" | Untested skills have issues. Always. |
+| "I'll test if problems emerge" | Test BEFORE deploying. |
+| "I'm confident it's good" | Overconfidence guarantees issues. Test anyway. |
+
+## Skill Creation Checklist
+
+**RED Phase:**
+- [ ] Create pressure scenarios (3+ combined pressures for discipline skills)
+- [ ] Run scenarios WITHOUT skill — document baseline behavior verbatim
+- [ ] Identify patterns in rationalizations/failures
+
+**GREEN Phase:**
+- [ ] Name uses only letters, numbers, hyphens
+- [ ] YAML frontmatter with `name` and `description` fields
+- [ ] Description starts with "Use when..." — triggering conditions only
+- [ ] Description written in third person
+- [ ] Keywords throughout for search
+- [ ] Clear overview with core principle
+- [ ] Address specific baseline failures from RED phase
+- [ ] Run scenarios WITH skill — verify agents now comply
+
+**REFACTOR Phase:**
+- [ ] Identify NEW rationalizations from testing
+- [ ] Add explicit counters for discipline skills
+- [ ] Build rationalization table from all test iterations
+- [ ] Create red flags list
+- [ ] Re-test until bulletproof
+
+**Deployment:**
+- [ ] Skill file at `.claude/skills/mastermind/<name>.md`
+- [ ] Command file at `.claude/commands/mastermind/<name>.md`
+- [ ] Commit both files to git
+
+## The Bottom Line
+
+**Creating mastermind skills IS TDD for process documentation.**
+
+Same Iron Law: No skill without failing test first.
+Same cycle: RED (baseline) → GREEN (write skill) → REFACTOR (close loopholes).
+Same benefits: Better quality, fewer surprises, bulletproof results.

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

@@ -0,0 +1,156 @@
+---
+name: mastermind-skills
+description: Mastermind skills — list, sync, and map skills available to org agents. Scans .claude/skills/ directory and shows which roles have access to which skill domains.
+type: domain-skill
+default_mode: auto
+---
+
+# Mastermind Skills
+
+This skill is invoked by `mastermind:skills` or directly via `/mastermind:skills`.
+
+---
+
+## Inputs
+
+- `brain_context`: BRAIN CONTEXT block (injected by command, or loaded below if standalone)
+- `org_name`: org to inspect skills for (optional — shows all skills if omitted)
+- `action`: list | sync | map | enable | disable
+- `skill_name`: skill slug (required for enable/disable)
+- `role_id`: role to map skill to (optional)
+- `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 — Scan Skills Directory
+
+```bash
+skillsDir=".claude/skills"
+[ ! -d "$skillsDir" ] && { echo "ERROR: No .claude/skills/ directory found."; exit 1; }
+
+# List all skill files recursively
+allSkills=$(find "$skillsDir" -name "*.md" ! -name "_*" | sort)
+```
+
+---
+
+## Step 2 — Execute Action
+
+### list (default)
+
+Display all available skills with metadata:
+
+```bash
+echo "AVAILABLE SKILLS"
+echo "────────────────────────────────────────────────────────"
+printf "%-30s %-15s %-10s %s\n" "NAME" "TYPE" "MODE" "DESCRIPTION"
+echo "────────────────────────────────────────────────────────"
+
+for f in $allSkills; do
+  skillSlug=$(basename "$f" .md)
+  domain=$(dirname "$f" | sed "s|$skillsDir/||")
+  skillType=$(grep -m1 "^type:" "$f" 2>/dev/null | awk '{print $2}')
+  skillMode=$(grep -m1 "^default_mode:" "$f" 2>/dev/null | awk '{print $2}')
+  skillDesc=$(grep -m1 "^description:" "$f" 2>/dev/null | sed 's/^description: //' | cut -c1-60)
+  printf "%-30s %-15s %-10s %s\n" "${domain}:${skillSlug}" "${skillType:-skill}" "${skillMode:-auto}" "$skillDesc"
+done
+
+echo ""
+echo "Total: $(echo "$allSkills" | wc -l | tr -d ' ') skills"
+```
+
+### map
+
+Show which skills are mapped to each role in the org:
+
+```bash
+orgFile=".monomind/orgs/${org_name}.json"
+[ ! -f "$orgFile" ] && { echo "ERROR: Org '$org_name' not found."; exit 1; }
+
+echo "SKILL MAP — org: $org_name"
+echo "────────────────────────────────────────────────────────"
+
+jq -r '(.roles // [])[] | "[\(.id)] \(.title)  agent_type=\(.agent_type)"' "$orgFile" | while IFS= read -r line; do
+  echo "$line"
+  roleId=$(echo "$line" | grep -o '^\[[^]]*\]' | tr -d '[]')
+  # Show skills configured for this role
+  mappedSkills=$(jq -r --arg id "$roleId" \
+    '(.roles // [])[] | select(.id == $id) | .skills // [] | join(", ")' \
+    "$orgFile" 2>/dev/null)
+  if [ -n "$mappedSkills" ] && [ "$mappedSkills" != "null" ]; then
+    echo "  Skills: $mappedSkills"
+  else
+    echo "  Skills: (inherited from agent_type)"
+  fi
+  echo ""
+done
+```
+
+### sync
+
+Refresh the skill registry by re-scanning `.claude/skills/` and updating org config with available skill slugs:
+
+```bash
+skillsDir=".claude/skills"
+skillList=$(find "$skillsDir" -name "*.md" ! -name "_*" -exec basename {} .md \; | sort | jq -Rsc 'split("\n") | map(select(. != ""))')
+
+if [ -n "$org_name" ]; then
+  orgFile=".monomind/orgs/${org_name}.json"
+  tmp="${orgFile}.tmp"
+  jq --argjson skills "$skillList" '.available_skills = $skills' "$orgFile" > "$tmp" && mv "$tmp" "$orgFile"
+  echo "Synced $(echo "$skillList" | jq 'length') skills → org: $org_name"
+else
+  echo "Available skills:"
+  echo "$skillList" | jq -r '.[]'
+  echo ""
+  echo "Pass --org <name> to sync skills into a specific org config."
+fi
+```
+
+### enable / disable
+
+Add or remove a skill from a role's allowed list:
+
+```bash
+orgFile=".monomind/orgs/${org_name}.json"
+[ ! -f "$orgFile" ] && { echo "ERROR: Org '$org_name' not found."; exit 1; }
+[ -z "$skill_name" ] && { echo "ERROR: --skill-name required."; exit 1; }
+[ -z "$role_id" ] && { echo "ERROR: --role-id required for enable/disable."; exit 1; }
+
+tmp="${orgFile}.tmp"
+if [ "$action" = "enable" ]; then
+  jq --arg id "$role_id" --arg skill "$skill_name" \
+    '.roles = [(.roles // [])[] | if .id == $id then .skills = ((.skills // []) + [$skill] | unique) else . end]' \
+    "$orgFile" > "$tmp" && mv "$tmp" "$orgFile"
+  echo "Enabled skill '$skill_name' for role '$role_id'"
+else
+  jq --arg id "$role_id" --arg skill "$skill_name" \
+    '.roles = [(.roles // [])[] | if .id == $id then .skills = ((.skills // []) | map(select(. != $skill))) else . end]' \
+    "$orgFile" > "$tmp" && mv "$tmp" "$orgFile"
+  echo "Disabled skill '$skill_name' for role '$role_id'"
+fi
+```
+
+---
+
+## Step 3 — Return Output
+
+```yaml
+domain: ops
+status: complete
+action: <action>
+org: <org_name if provided>
+skills_found: <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/spec-reviewer-prompt.md

@@ -0,0 +1,63 @@
+# Spec Compliance Reviewer Prompt Template
+
+Use this template when dispatching a spec compliance reviewer subagent from `mastermind:taskdev`.
+
+**Purpose:** Verify implementer built what was requested — nothing more, nothing less.
+
+**Dispatch BEFORE code quality review.** Spec compliance always runs first.
+
+```
+Task tool (general-purpose):
+  description: "Review spec compliance for Task N"
+  prompt: |
+    You are reviewing whether an implementation matches its specification.
+
+    ## What Was Requested
+
+    [FULL TEXT of task requirements — paste from plan]
+
+    ## What Implementer Claims They Built
+
+    [From implementer's report]
+
+    ## CRITICAL: Do Not Trust the Report
+
+    The implementer may have finished quickly or missed things. Their report may be
+    incomplete, inaccurate, or optimistic. You MUST verify everything independently.
+
+    **DO NOT:**
+    - Take their word for what they implemented
+    - Trust their claims about completeness
+    - Accept their interpretation of requirements
+
+    **DO:**
+    - Read the actual code they wrote
+    - Compare actual implementation to requirements line by line
+    - Check for missing pieces they claimed to implement
+    - Look for extra features they didn't mention
+
+    ## Your Job
+
+    Read the implementation code and verify:
+
+    **Missing requirements:**
+    - Did they implement everything that was requested?
+    - Are there requirements they skipped or missed?
+    - Did they claim something works but didn't actually implement it?
+
+    **Extra/unneeded work:**
+    - Did they build things that weren't requested?
+    - Did they over-engineer or add unnecessary features?
+    - Did they add "nice to haves" that weren't in spec?
+
+    **Misunderstandings:**
+    - Did they interpret requirements differently than intended?
+    - Did they solve the wrong problem?
+    - Did they implement the right feature the wrong way?
+
+    **Verify by reading code, not by trusting the report.**
+
+    Report:
+    - ✅ Spec compliant (if everything matches after code inspection)
+    - ❌ Issues found: [list specifically what's missing or extra, with file:line references]
+```

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

@@ -0,0 +1,138 @@
+---
+name: mastermind-stoporg
+description: Mastermind stoporg — stop a running scheduled org loop by setting its status to "stopped". The next scheduled wakeup will read the status, skip all work, and not reschedule. Loop dies within one interval — no orphaned wakeups.
+type: domain-skill
+default_mode: auto
+---
+
+# Mastermind Stop Org
+
+This skill is invoked by `mastermind:stoporg` or directly via `/mastermind:stoporg`.
+
+---
+
+## Inputs
+
+- `org_name`: name of the org to stop (matches `.monomind/orgs/<org_name>.json`)
+- `session_id`: session ID generated by the command wrapper
+- `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 — Validate Org
+
+```bash
+orgFile=".monomind/orgs/${org_name}.json"
+[ ! -f "$orgFile" ] && {
+  echo "ERROR: Org '${org_name}' not found."
+  echo "Available orgs: $(ls .monomind/orgs/*.json 2>/dev/null | grep -vE -- '-approvals|-state|-activity|-goals|-routines|-projects|-members|-issues|-workspaces|-worktrees|-environments|-plugins|-adapters|-bootstrap|-threads|-budgets|-project-workspaces|-approval-comments' | xargs -I{} basename {} .json | tr '\n' ' ')"
+  exit 1
+}
+```
+
+Read current status:
+```bash
+current_status=$(jq -r '.status // "no-schedule"' "$orgFile")
+has_schedule=$(jq -r 'if .loop.poll_interval_minutes then "yes" else "no" end' "$orgFile")
+```
+
+If `has_schedule == "no"`:
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+CTRL_URL=$(jq -r '.url // "http://localhost:4242"' "$REPO_ROOT/.monomind/control.json" 2>/dev/null || echo "http://localhost:4242")
+# Write stop file so any running boss agent detects it at next loop iteration
+mkdir -p ".monomind/orgs/.stops"
+touch ".monomind/orgs/.stops/${org_name}.stop"
+# Also POST to the control server in case a dashboard-started instance is running
+curl -s -X POST "${CTRL_URL}/api/orgs/${org_name}/stop" >/dev/null 2>&1 || true
+echo "Stop signal sent to org '${org_name}' (non-scheduled). The boss agent will exit at the next loop checkpoint."
+```
+- Exit.
+
+If `current_status == "stopped"`:
+- Print: "Org '<org_name>' is already stopped."
+- Exit.
+
+---
+
+## Step 2 — Set Status to Stopped and Clear next_run
+
+```bash
+orgFile=".monomind/orgs/${org_name}.json"
+tmp="${orgFile}.tmp"
+# Clear next_run to avoid showing a stale future timestamp in orgstatus
+jq '.status = "stopped" | if .loop then .loop.next_run = null else . end' "$orgFile" > "$tmp" && mv "$tmp" "$orgFile"
+```
+
+---
+
+## Step 3 — Write Stop File (for any running boss agents)
+
+Any persistent boss agent checks for this file at the start of each loop iteration:
+
+```bash
+mkdir -p .monomind/orgs/.stops
+touch ".monomind/orgs/.stops/${org_name}.stop"
+```
+
+---
+
+## Step 4 — Emit Dashboard Events
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+CTRL_URL=$(jq -r '.url // "http://localhost:4242"' "$REPO_ROOT/.monomind/control.json" 2>/dev/null || echo "http://localhost:4242")
+
+# org:stop — signals dashboard to update status to stopped
+curl -s -X POST "${CTRL_URL}/api/mastermind/event" \
+  -H "Content-Type: application/json" \
+  -d "$(jq -cn \
+    --arg session "${session_id:-manual}" \
+    --arg org "$org_name" \
+    --arg proj "$REPO_ROOT" \
+    '{type:"org:stop",session:$session,org:$org,project:$proj,ts:(now*1000|floor)}')" || true
+```
+
+---
+
+## Step 5 — Report to User
+
+```
+✓ Org "<org_name>" stopped.
+
+  Current status: stopped
+  The loop will exit at its next scheduled wakeup without rescheduling.
+  Loop fully dead within: ≤$(jq -r '.loop.poll_interval_minutes // "?"' "$orgFile") minutes
+
+  To restart: /mastermind:runorg --org <org_name>
+  Status:     /mastermind:orgstatus --org <org_name>
+```
+
+---
+
+## Step 6 — Return Output
+
+```yaml
+domain: ops
+status: complete
+decisions:
+  - what: "Org <org_name> stopped"
+    why: "status set to 'stopped'; next wakeup exits without rescheduling"
+    confidence: 1.0
+    outcome: shipped
+next_actions:
+  - "To restart: /mastermind:runorg --org <org_name>"
+  - "To check current state: /mastermind:orgstatus --org <org_name>"
+```
+
+---
+
+## Step 7 — Brain Write (standalone only)
+
+If `caller` is not "command", follow _protocol.md Brain Write Procedure for domain `ops`.