monomind 2.7.12 → 2.7.13

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

@@ -1,447 +0,0 @@
----
-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-<name>/
-    SKILL.md               # Main skill (required — a bare <name>.md does NOT register)
-    *-prompt.md            # Optional supporting files (prompt templates, references)
-
-.claude/commands/mastermind/
-  <name>.md                # Command entry point (required)
-```
-
-**One top-level directory per skill** — Claude Code only registers `.claude/skills/<dir>/SKILL.md`, under the directory's own name. Grouping folders inside `.claude/skills/` do NOT register their children, so never nest. The `mastermind-` prefix on every skill directory is what prevents collisions with other skills, so never omit it — `monomind init` ships every `mastermind-*` directory automatically. Command wrappers invoke `Skill("mastermind-<name>")`.
-
-## 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 `mastermind-repeat/SKILL.md`.
-
-Parse `$ARGUMENTS` for `--auto`, `--confirm`, `--project <name>`, and remaining text.
-
-Load brain context (follow `mastermind-protocol/SKILL.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 `mastermind-protocol/SKILL.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
-```
-
-### 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:
-- 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
-```
-
-**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
-
-Each mastermind skill is one directory holding a single `SKILL.md`. Keep everything inline in that file. 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 supporting `*-prompt.md` files inside the owning skill's directory, referenced as `./<name>-prompt.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"
-- 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)
-
-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.
-
-### 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 |
-|--------|---------|
-| "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. |
-| "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
-
-**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
-- [ ] 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:**
-- [ ] 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>/SKILL.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
-
-**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/SKILL.md

@@ -1,156 +0,0 @@
----
-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 mastermind-protocol/SKILL.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 mastermind-protocol/SKILL.md Brain Write Procedure for domain `ops`.