monomind 2.2.0 → 2.3.0

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

@@ -42,34 +42,51 @@ fi
 
 ## Step 2 — Render Org Table
 
-For each org file (skip state/approvals files), extract and display:
+For each org file (skip state/approvals files), extract and display. v2 orgs
+(Org Runtime v2, the default since 2026-07) carry `schedule` ("30m"/"2h") in the
+config and their live state in `.monomind/orgs/<name>/runtime.json`; only legacy
+v1 orgs have a `.loop` block.
 
 ```bash
 echo ""
-printf "%-28s %-10s %-12s %-22s %-22s\n" "ORG" "STATUS" "SCHEDULE" "LAST RUN" "NEXT RUN"
-printf "%-28s %-10s %-12s %-22s %-22s\n" "---" "------" "--------" "--------" "--------"
+printf "%-28s %-14s %-12s %-22s\n" "ORG" "STATUS" "SCHEDULE" "LAST RUN"
+printf "%-28s %-14s %-12s %-22s\n" "---" "------" "--------" "--------"
 
 for f in $orgFiles; do
-  name=$(jq -r '.name // "(unnamed)"' "$f" 2>/dev/null)
+  name=$(basename "$f" .json)
   goal=$(jq -r '.goal // ""' "$f" 2>/dev/null | cut -c1-55)
-  status=$(jq -r '.status // "—"' "$f" 2>/dev/null)
-  interval=$(jq -r 'if .loop.poll_interval_minutes then "\(.loop.poll_interval_minutes)m" else "manual" end' "$f" 2>/dev/null)
-  last_run=$(jq -r '.loop.last_run // "—"' "$f" 2>/dev/null | sed 's/T/ /;s/Z//')
-  next_run=$(jq -r '.loop.next_run // "—"' "$f" 2>/dev/null | sed 's/T/ /;s/Z//')
-  
-  # Status indicator — distinguish non-scheduled (manual) from scheduled loop states
-  if [ "$interval" = "manual" ]; then
-    indicator="■ persistent"
-  else
+  schedule=$(jq -r '.schedule // empty' "$f" 2>/dev/null)
+  loop_interval=$(jq -r '.loop.poll_interval_minutes // empty' "$f" 2>/dev/null)
+
+  if [ -n "$loop_interval" ]; then
+    # legacy v1 scheduled org — state lives in the config's status field
+    interval="${loop_interval}m (v1)"
+    status=$(jq -r '.status // "—"' "$f" 2>/dev/null)
     case "$status" in
       active)  indicator="● active" ;;
-      stopped) indicator="○ stopped" ;;
       paused)  indicator="⏸ paused" ;;
-      *)       indicator="— unknown" ;;
+      *)       indicator="○ stopped" ;;
     esac
+    last_run=$(jq -r '.loop.last_run // "—"' "$f" 2>/dev/null | sed 's/T/ /;s/Z//')
+  else
+    # v2 org — live state is in runtime.json (crashed = running record, dead pid)
+    interval="${schedule:-manual}"
+    rt=".monomind/orgs/${name}/runtime.json"
+    rt_status=$(jq -r '.status // "never run"' "$rt" 2>/dev/null || echo "never run")
+    rt_pid=$(jq -r '.pid // 0' "$rt" 2>/dev/null || echo 0)
+    if [ "$rt_status" = "running" ] && [ "$rt_pid" -gt 0 ] && ! kill -0 "$rt_pid" 2>/dev/null; then
+      indicator="✗ crashed"
+    elif [ "$rt_status" = "running" ]; then
+      indicator="● running"
+    elif [ "$rt_status" = "never run" ]; then
+      indicator="· never run"
+    else
+      indicator="○ ${rt_status}"
+    fi
+    last_run=$(jq -r '.updated // "—"' "$rt" 2>/dev/null | sed 's/T/ /;s/\..*Z//' || echo "—")
   fi
-  
-  printf "%-28s %-10s %-12s %-22s %-22s\n" "$name" "$indicator" "$interval" "$last_run" "$next_run"
+
+  printf "%-28s %-14s %-12s %-22s\n" "$name" "$indicator" "$interval" "$last_run"
   echo "  └ $goal"
   echo ""
 done
@@ -82,10 +99,14 @@ done
 ```
 COMMANDS
 ────────
+  monomind org run <name>                Run an org once in the foreground
+  monomind org serve                     Host all scheduled orgs as a daemon
+  monomind org stop <name>               Stop a running org
+  monomind org status [name]             Runtime state (detects crashes)
+  monomind org validate [name]           Check config against the runtime schema
   /mastermind:orgstatus --org <name>     Detailed status, last runs, activity
-  /mastermind:runorg --org <name>        Start (or restart) a scheduled org
-  /mastermind:stoporg --org <name>       Stop a running scheduled org
   /mastermind:createorg <goal>           Create a new org
+  /mastermind:runorg --org <name>        (legacy v1 orgs only — deprecated)
 ```
 
 ---

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

@@ -39,20 +39,37 @@ orgFile=".monomind/orgs/${org_name}.json"
 
 ## Step 2 — Extract Fields
 
+An org is **v2** (Org Runtime v2 — the default since 2026-07) when it has no
+`.loop` block; its schedule is the top-level `schedule` field and its live state
+is `.monomind/orgs/<name>/runtime.json`. Only legacy v1 orgs have `.loop`,
+`topology`, `board_id`, or `agent_type` on roles.
+
 ```bash
 name=$(jq -r '.name // "(unnamed)"' "$orgFile")
 goal=$(jq -r '.goal // "(no goal set)"' "$orgFile")
 status=$(jq -r '.status // "no-schedule"' "$orgFile")
-topology=$(jq -r '.topology // "hierarchical"' "$orgFile")
 role_count=$(jq '.roles | length' "$orgFile")
 created_at=$(jq -r '.created_at // "-"' "$orgFile")
 
-# Loop fields (scheduled orgs only)
+# v1 loop fields (legacy scheduled orgs only)
 has_schedule=$(jq -r 'if .loop.poll_interval_minutes then "yes" else "no" end' "$orgFile")
 poll_interval=$(jq -r '.loop.poll_interval_minutes // ""' "$orgFile")
 last_run=$(jq -r '.loop.last_run // "never"' "$orgFile")
 next_run=$(jq -r '.loop.next_run // "not scheduled"' "$orgFile")
 run_prompt_file=$(jq -r '.loop.run_prompt_file // ""' "$orgFile")
+
+# v2 fields
+is_v2=$([ "$has_schedule" = "no" ] && echo yes || echo no)
+v2_schedule=$(jq -r '.schedule // empty' "$orgFile")
+budget=$(jq -r '.run_config.budget_tokens // 1000000' "$orgFile")
+rtFile=".monomind/orgs/${org_name}/runtime.json"
+rt_status=$(jq -r '.status // "never run"' "$rtFile" 2>/dev/null || echo "never run")
+rt_run=$(jq -r '.run // ""' "$rtFile" 2>/dev/null || echo "")
+rt_pid=$(jq -r '.pid // 0' "$rtFile" 2>/dev/null || echo 0)
+rt_updated=$(jq -r '.updated // "-"' "$rtFile" 2>/dev/null || echo "-")
+if [ "$rt_status" = "running" ] && [ "$rt_pid" -gt 0 ] && ! kill -0 "$rt_pid" 2>/dev/null; then
+  rt_status="crashed (stale runtime.json, pid ${rt_pid} gone)"
+fi
 ```
 
 ---
@@ -65,9 +82,19 @@ echo "ORG: $name"
 echo "════════════════════════════════════════════════"
 echo "  Goal:      $goal"
 echo "  Created:   $created_at"
-echo "  Topology:  $topology  |  Roles: $role_count"
+echo "  Roles:     $role_count"
 echo ""
 
+if [ "$is_v2" = "yes" ]; then
+  echo "RUNTIME (Org Runtime v2)"
+  echo "────────────────────────"
+  echo "  Status:    $rt_status${rt_run:+  (run $rt_run)}"
+  echo "  Updated:   $rt_updated"
+  echo "  Schedule:  ${v2_schedule:-manual — run with: monomind org run $name}"
+  echo "  Budget:    $budget tokens (split across roles)"
+  echo ""
+fi
+
 if [ "$has_schedule" = "yes" ]; then
   echo "SCHEDULED LOOP"
   echo "──────────────"
@@ -88,22 +115,28 @@ fi
 
 echo "ROLES"
 echo "─────"
-jq -r '(.roles // [])[] | "  • [\(.id)] \(.title)  →  \(.agent_type)  (\(.reports_to // "top"))"' "$orgFile"
+jq -r '(.roles // [])[] | "  • [\(.id)] \(.title // .id)  →  \(.agent_type // .type // "specialist")  (reports to: \(.reports_to // "top"))"' "$orgFile"
 echo ""
 
 echo "HEALTH"
 echo "──────"
 
-# Board / column IDs
-board_id=$(jq -r '.board_id // ""' "$orgFile")
-todo_col=$(jq -r '.todo_col_id // ""' "$orgFile")
-doing_col=$(jq -r '.doing_col_id // ""' "$orgFile")
-done_col=$(jq -r '.done_col_id // ""' "$orgFile")
-
-if [ -n "$board_id" ] && [ -n "$todo_col" ] && [ -n "$doing_col" ] && [ -n "$done_col" ]; then
-  echo "  Board:     ✓ task board configured (${board_id})"
+if [ "$is_v2" = "yes" ]; then
+  # v2 health = does the config still start? (schema + structural invariants)
+  npx -y monomind@latest org validate "$name" >/dev/null 2>&1 \
+    && echo "  Config:    ✓ valid (monomind org validate)" \
+    || echo "  Config:    ✗ INVALID — run: monomind org validate $name"
 else
-  echo "  Board:     ✗ task board IDs missing — re-run /mastermind:createorg --name ${name} to rebuild"
+  # v1 health: board / column IDs
+  board_id=$(jq -r '.board_id // ""' "$orgFile")
+  todo_col=$(jq -r '.todo_col_id // ""' "$orgFile")
+  doing_col=$(jq -r '.doing_col_id // ""' "$orgFile")
+  done_col=$(jq -r '.done_col_id // ""' "$orgFile")
+  if [ -n "$board_id" ] && [ -n "$todo_col" ] && [ -n "$doing_col" ] && [ -n "$done_col" ]; then
+    echo "  Board:     ✓ task board configured (${board_id})"
+  else
+    echo "  Board:     ✗ task board IDs missing — re-run /mastermind:createorg --name ${name} to rebuild"
+  fi
 fi
 
 # Pending approvals
@@ -117,9 +150,9 @@ else
   echo "  Approvals: ✓ no approvals file"
 fi
 
-# Stop file (pending stop signal)
-stopFile=".monomind/orgs/.stops/${org_name}.stop"
-[ -f "$stopFile" ] && echo "  Stop file: ⚠ PRESENT — a stop signal is queued for this org"
+# Stop file (pending stop signal) — v2 daemons poll <org>/stop; v1 used .stops/
+[ -f ".monomind/orgs/${org_name}/stop" ] && echo "  Stop file: ⚠ PRESENT (v2) — daemon will exit within 2s of seeing it"
+[ -f ".monomind/orgs/.stops/${org_name}.stop" ] && echo "  Stop file: ⚠ PRESENT (v1 legacy path)"
 
 # Loop prompt file (scheduled orgs)
 if [ "$has_schedule" = "yes" ]; then
@@ -137,17 +170,30 @@ echo ""
 ## Step 4 — Show Recent Activity (if available)
 
 ```bash
-activityFile=".monomind/orgs/${org_name}-activity.jsonl"
-if [ -f "$activityFile" ]; then
-  echo "RECENT ACTIVITY (last 5)"
-  echo "────────────────────────"
-  tail -5 "$activityFile" | while IFS= read -r line; do
-    ts=$(echo "$line" | jq -r '.ts // ""')
-    type=$(echo "$line" | jq -r '.type // ""')
-    pending=$(echo "$line" | jq -r '.pending // ""')
-    echo "  $ts  $type  ${pending:+pending=$pending}"
-  done
-  echo ""
+if [ "$is_v2" = "yes" ]; then
+  # v2: the durable record is bus.jsonl inside the most recent run directory
+  latest_bus=$(ls -t .monomind/orgs/"${org_name}"/run-*/bus.jsonl 2>/dev/null | head -1)
+  if [ -n "$latest_bus" ]; then
+    echo "RECENT ACTIVITY (last 5 bus events — $(dirname "$latest_bus" | xargs basename))"
+    echo "────────────────────────"
+    tail -5 "$latest_bus" | while IFS= read -r line; do
+      echo "$line" | jq -r '"  \(.ts // "" | if type=="number" then (./1000 | todate) else . end)  \(.type // "")  \(.from // "")\(if .to then " → " + .to else "" end)  \(.msg // .tool // "" | tostring | .[0:60])"' 2>/dev/null
+    done
+    echo ""
+  fi
+else
+  activityFile=".monomind/orgs/${org_name}-activity.jsonl"
+  if [ -f "$activityFile" ]; then
+    echo "RECENT ACTIVITY (last 5)"
+    echo "────────────────────────"
+    tail -5 "$activityFile" | while IFS= read -r line; do
+      ts=$(echo "$line" | jq -r '.ts // ""')
+      type=$(echo "$line" | jq -r '.type // ""')
+      pending=$(echo "$line" | jq -r '.pending // ""')
+      echo "  $ts  $type  ${pending:+pending=$pending}"
+    done
+    echo ""
+  fi
 fi
 ```
 
@@ -156,25 +202,28 @@ fi
 ## Step 5 — Show Lifecycle Commands
 
 ```bash
-if [ "$has_schedule" = "yes" ]; then
-  echo "ACTIONS"
-  echo "───────"
+echo "ACTIONS"
+echo "───────"
+if [ "$is_v2" = "yes" ]; then
+  case "$rt_status" in
+    running*) echo "  Stop:         monomind org stop $name" ;;
+    crashed*) echo "  Close out:    monomind org mark-complete $name" ;;
+    *)        echo "  Run:          monomind org run $name${v2_schedule:+   (or host on schedule: monomind org serve)}" ;;
+  esac
+  echo "  Logs:         monomind org logs $name --follow"
+  echo "  Report:       monomind org report $name   (add --all for run history)"
+  echo "  Validate:     monomind org validate $name"
+  echo "  Settings:     /mastermind:org-settings --org $name"
+elif [ "$has_schedule" = "yes" ]; then
   case "$status" in
-    active|paused)
-      echo "  Stop loop:    /mastermind:stoporg --org $name"
-      ;;
-    stopped)
-      echo "  Start loop:   /mastermind:runorg --org $name"
-      ;;
+    active|paused) echo "  Stop loop:    /mastermind:stoporg --org $name" ;;
+    stopped)       echo "  Start loop:   /mastermind:runorg --org $name  (legacy v1)" ;;
   esac
   echo "  Edit prompt:  \$EDITOR $run_prompt_file"
-  echo "  All orgs:     /mastermind:orgs"
 else
-  echo "ACTIONS"
-  echo "───────"
-  echo "  Run org:      /mastermind:runorg --org $name"
-  echo "  All orgs:     /mastermind:orgs"
+  echo "  Run org:      /mastermind:runorg --org $name  (legacy v1)"
 fi
+echo "  All orgs:     /mastermind:orgs"
 echo ""
 ```
 

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

@@ -49,6 +49,12 @@ This structure informs the task decomposition. Each task should produce self-con
 
 ---
 
+## Task Right-Sizing
+
+A task is the smallest unit that carries its own test cycle and is worth a fresh reviewer's gate. When drawing task boundaries: fold setup, configuration, scaffolding, and documentation steps into the task whose deliverable needs them; split only where a reviewer could meaningfully reject one task while approving its neighbor. Each task ends with an independently testable deliverable.
+
+---
+
 ## Bite-Sized Task Granularity
 
 **Each step is one action (2-5 minutes):**
@@ -75,6 +81,13 @@ This structure informs the task decomposition. Each task should produce self-con
 
 **Tech Stack:** [Key technologies/libraries]
 
+## Global Constraints
+
+[The spec's project-wide requirements — version floors, dependency limits,
+naming and copy rules, platform requirements — one line each, with exact
+values copied verbatim from the spec. Every task's requirements implicitly
+include this section.]
+
 ---
 ```
 
@@ -90,6 +103,12 @@ This structure informs the task decomposition. Each task should produce self-con
 - Modify: `exact/path/to/existing.py:123-145`
 - Test: `tests/exact/path/to/test.py`
 
+**Interfaces:**
+- Consumes: [what this task uses from earlier tasks — exact signatures]
+- Produces: [what later tasks rely on — exact function names, parameter
+  and return types. A task's implementer sees only their own task; this
+  block is how they learn the names and types neighboring tasks use.]
+
 - [ ] **Step 1: Write the failing test**
 
 ```python

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

@@ -161,6 +161,12 @@ description: Use when implementation is complete and you need to decide how to i
 description: Use when receiving code review feedback before implementing suggestions
 ```
 
+### Descriptive Naming
+
+**Use active voice, verb-first:**
+- ✅ `creating-skills` not `skill-creation`
+- ✅ `condition-based-waiting` not `async-test-helpers`
+
 ### Keyword Coverage
 
 Use words Claude would search for:
@@ -190,6 +196,33 @@ Use words Claude would search for:
 See mastermind/worktree.md
 ```
 
+**Why no @ links:** `@` syntax force-loads files immediately, consuming context before it's needed. Name the skill; let the reader invoke it.
+
+## Flowchart Usage
+
+**Use flowcharts ONLY for:**
+- Non-obvious decision points
+- Process loops where you might stop too early
+- "When to use A vs B" decisions
+
+**Never use flowcharts for:**
+- Reference material → tables, lists
+- Code examples → markdown blocks
+- Linear instructions → numbered lists
+- Labels without semantic meaning (step1, helper2)
+
+## Code Examples
+
+**One excellent example beats many mediocre ones.** Choose the most relevant language for the domain.
+
+**Good example:** complete and runnable, well-commented explaining WHY, from a real scenario, ready to adapt.
+
+**Don't:** implement in 5+ languages, create fill-in-the-blank templates, write contrived examples.
+
+## File Organization
+
+Mastermind skills are single files in a flat namespace. Keep everything inline. If a skill genuinely needs heavy reference material (500+ lines of API docs), condense it to what agents actually retrieve — a skill nobody can afford to load teaches nothing. Reusable prompt templates (like taskdev's implementer/reviewer prompts) live as sibling `*-prompt.md` files in the skills directory.
+
 ## The Iron Law (Same as TDD)
 
 ```
@@ -205,8 +238,83 @@ Edit skill without testing? Same violation.
 - Not for "simple additions"
 - Not for "just adding a section"
 - Not for "documentation updates"
+- Don't keep untested changes as "reference"
+- Don't "adapt" while running tests
 - Delete means delete
 
+## Testing All Skill Types
+
+Different skill types need different test approaches:
+
+### Discipline-Enforcing Skills (rules/requirements)
+
+**Examples:** tdd, verify, design-before-code gates
+
+**Test with:** academic questions (do they understand the rules?), pressure scenarios (do they comply under stress?), multiple pressures combined (time + sunk cost + exhaustion). Identify rationalizations and add explicit counters.
+
+**Success criteria:** agent follows the rule under maximum pressure.
+
+### Technique Skills (how-to guides)
+
+**Test with:** application scenarios (can they apply it correctly?), variation scenarios (edge cases?), missing-information tests (do the instructions have gaps?).
+
+**Success criteria:** agent successfully applies the technique to a new scenario.
+
+### Pattern Skills (mental models)
+
+**Test with:** recognition scenarios (do they see when it applies?), application scenarios, counter-examples (do they know when NOT to apply?).
+
+**Success criteria:** agent correctly identifies when/how to apply the pattern.
+
+### Reference Skills (documentation/APIs)
+
+**Test with:** retrieval scenarios (can they find the right information?), application scenarios (can they use it correctly?), gap testing (are common use cases covered?).
+
+**Success criteria:** agent finds and correctly applies the reference information.
+
+## Match the Form to the Failure
+
+Before writing guidance, classify the baseline failure. The form that bulletproofs one failure type measurably backfires on another.
+
+| Baseline failure | Right form | Wrong form |
+|---|---|---|
+| Skips/violates a rule under pressure (knows better, does it anyway) | Prohibition + rationalization table + red flags (see Bulletproofing below) | Soft guidance ("prefer...", "consider...") |
+| Complies, but output has the wrong shape (bloated prompt, buried verdict, restated spec) | Positive recipe or contract: state what the output IS — its parts, in order | Prohibition list ("don't restate", "never narrate") |
+| Omits a required element from something they already produce | Structural: REQUIRED field or slot in the template they fill in | Prose reminders near the template |
+| Behavior should depend on a condition | Conditional keyed to an observable predicate ("if the brief exists, reference it") | Unconditional rule + exemption clauses |
+
+**Why prohibitions backfire on shaping problems:** under a competing incentive, agents negotiate with "don't X". A recipe leaves nothing to negotiate: the output matches the stated shape or it doesn't.
+
+**Rules for whichever form you pick:**
+- **No nuance clauses.** "Don't X unless it matters" reopens the negotiation. Express a real exception as its own conditional on an observable predicate.
+- **Exemption clauses don't scope.** "This limit doesn't apply to code blocks" still suppresses code blocks. If part of the output must be exempt, restructure so the rule can't reach it.
+
+## Bulletproofing Skills Against Rationalization
+
+Skills that enforce discipline (like TDD) need to resist rationalization. Agents are smart and will find loopholes when under pressure.
+
+**Scope:** this toolkit is for discipline failures — an agent that knows the rule and skips it under pressure. For wrong-shaped output or omitted elements, prohibition-based bulletproofing backfires; use the forms in Match the Form to the Failure instead.
+
+### Close Every Loophole Explicitly
+
+Don't just state the rule — forbid specific workarounds. "Write code before test? Delete it." becomes: "Delete it. Start over. No exceptions: don't keep it as 'reference', don't 'adapt' it while writing tests, don't look at it. Delete means delete."
+
+### Address "Spirit vs Letter" Arguments
+
+Add the foundational principle early: **"Violating the letter of the rules is violating the spirit of the rules."** This cuts off the entire class of "I'm following the spirit" rationalizations.
+
+### Build Rationalization Table
+
+Capture rationalizations from baseline testing. Every excuse agents make goes in the table as `| Excuse | Reality |` rows.
+
+### Create Red Flags List
+
+Make it easy for agents to self-check when rationalizing: a short list of the exact thoughts that mean STOP, ending with what to do instead.
+
+### Update the Description for Violation Symptoms
+
+Add to the description the symptoms of when you're ABOUT to violate the rule (e.g. "use when implementing any feature or bugfix, **before writing implementation code**").
+
 ## RED-GREEN-REFACTOR for Skills
 
 ### RED: Write Failing Test (Baseline)
@@ -226,6 +334,18 @@ Run same scenarios WITH skill. Agent should now comply.
 
 Agent found new rationalization? Add explicit counter. Re-test until bulletproof.
 
+### Micro-Test Wording Before Full Scenarios
+
+Full pressure-scenario runs are the final gate, but they are slow and expensive per iteration. Verify the wording itself first with micro-tests:
+
+1. **One fresh-context sample per call** — a single-shot subagent whose instructions embed the guidance in the realistic context it will live in (the full skill, not the guidance in isolation), given a task that tempts the failure.
+2. **Always include a no-guidance control.** If the control doesn't exhibit the failure, there is nothing to fix — stop, don't author the guidance.
+3. **5+ reps per variant.** Single samples lie.
+4. **Manually read every flagged match.** Template echoes and quoted counter-examples masquerade as hits; automated counts alone overstate both failure and success.
+5. **Variance is a metric.** When guidance lands, reps converge on the same shape. Five different interpretations across five reps means the wording isn't binding — tighten the form before adding words.
+
+Micro-tests verify wording; they do not replace pressure scenarios for discipline skills.
+
 ## Common Rationalizations for Skipping Testing
 
 | Excuse | Reality |
@@ -235,6 +355,40 @@ Agent found new rationalization? Add explicit counter. Re-test until bulletproof
 | "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. |
+| "Academic review is enough" | Reading ≠ using. Test application scenarios. |
+| "Too tedious to test" | Testing is less tedious than debugging a bad skill in production. |
+| "No time to test" | Deploying an untested skill wastes more time fixing it later. |
+
+**All of these mean: Test before deploying. No exceptions.**
+
+## Anti-Patterns
+
+### ❌ Narrative Example
+"In session 2025-10-03, we found empty projectDir caused..."
+**Why bad:** Too specific, not reusable
+
+### ❌ Multi-Language Dilution
+example-js.js, example-py.py, example-go.go
+**Why bad:** Mediocre quality, maintenance burden
+
+### ❌ Code in Flowcharts
+Flowchart nodes containing code statements
+**Why bad:** Can't copy-paste, hard to read
+
+### ❌ Generic Labels
+helper1, helper2, step3, pattern4
+**Why bad:** Labels should have semantic meaning
+
+## STOP: Before Moving to Next Skill
+
+**After writing ANY skill, you MUST STOP and complete the deployment process.**
+
+**Do NOT:**
+- Create multiple skills in batch without testing each
+- Move to the next skill before the current one is verified
+- Skip testing because "batching is more efficient"
+
+**The deployment checklist below is MANDATORY for EACH skill.** Deploying untested skills = deploying untested code.
 
 ## Skill Creation Checklist
 
@@ -251,6 +405,9 @@ Agent found new rationalization? Add explicit counter. Re-test until bulletproof
 - [ ] Keywords throughout for search
 - [ ] Clear overview with core principle
 - [ ] Address specific baseline failures from RED phase
+- [ ] Guidance form matches the failure type (see Match the Form to the Failure)
+- [ ] For behavior-shaping guidance: wording micro-tested against a no-guidance control (5+ reps, every flagged match read manually) — N/A for pure reference skills
+- [ ] One excellent example (not multi-language)
 - [ ] Run scenarios WITH skill — verify agents now comply
 
 **REFACTOR Phase:**
@@ -264,6 +421,20 @@ Agent found new rationalization? Add explicit counter. Re-test until bulletproof
 - [ ] Skill file at `.claude/skills/mastermind/<name>.md`
 - [ ] Command file at `.claude/commands/mastermind/<name>.md`
 - [ ] Commit both files to git
+- [ ] Mirror both files into `packages/@monomind/cli/.claude/` (the npm-shipped copy)
+
+## Discovery Workflow
+
+How future agents find your skill:
+
+1. **Encounters problem** ("tests are flaky")
+2. **Searches skills** (greps descriptions, browses the namespace)
+3. **Finds the skill** (description matches)
+4. **Scans overview** (is this relevant?)
+5. **Reads patterns** (quick reference table)
+6. **Loads example** (only when implementing)
+
+**Optimize for this flow** — put searchable terms early and often.
 
 ## The Bottom Line
 

package/packages/@monomind/cli/.claude/skills/mastermind-skills/spec-reviewer-prompt.md

@@ -14,11 +14,28 @@ Task tool (general-purpose):
 
     ## What Was Requested
 
-    [FULL TEXT of task requirements — paste from plan]
+    Read this file first — it is the task's requirements, with the exact
+    values that bind the implementation:
+
+    [TASK_BRIEF_PATH — e.g. .monomind/taskdev/task-N-brief.md]
+
+    ## Global Constraints
+
+    [Copied verbatim from the plan's Global Constraints section — exact
+    values, formats, and cross-component relationships that bind this task]
 
     ## What Implementer Claims They Built
 
-    [From implementer's report]
+    Read the implementer's report file:
+
+    [REPORT_FILE_PATH — e.g. .monomind/taskdev/task-N-report.md]
+
+    ## Diff to Review
+
+    Read this file — it contains the commit list, stat summary, and full
+    diff for the task:
+
+    [DIFF_FILE_PATH — e.g. .monomind/taskdev/task-N-review.diff]
 
     ## CRITICAL: Do Not Trust the Report
 

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

@@ -42,16 +42,18 @@ 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"`:
+If `has_schedule == "no"` — this is a **v2 org** (Org Runtime v2 has `schedule`,
+never `.loop`). Its daemon polls `.monomind/orgs/<name>/stop` every 2s, which is
+exactly what `monomind org stop` writes — use the CLI, not the v1 `.stops/` path:
+
 ```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"
+npx -y monomind@latest org stop "${org_name}" \
+  || { mkdir -p ".monomind/orgs/${org_name}"; date -u +%Y-%m-%dT%H:%M:%SZ > ".monomind/orgs/${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."
+echo "Stop requested for org '${org_name}' (v2 daemon exits within 2s)."
 ```
 - Exit.