mastermind

What this skill does

# Mastermind - Multi-Project Progress Management

Use this skill when the user mentions "mastermind", "track projects", "project overview", "sync sessions", "project progress", or wants to manage multiple ongoing projects from a central location.

---

## Execution Principles

**Trust the specifications. Do NOT verify documented structures.**

All mastermind commands include complete specifications for:
- File formats (JSONL structure, YAML schema)
- Directory layouts (vault structure, Claude session paths)
- Data schemas (sync state, config format)

**When executing a command:**
1. Read the command specification completely
2. Execute each step as documented
3. Use the exact paths, formats, and commands specified
4. Do NOT add "exploratory" or "verification" steps

**Anti-patterns:**
- Running `head`/`grep` to "understand" file formats already documented
- Using `ls` to "discover" directory structures already specified
- Parsing files to "check" schemas already defined
- Adding preliminary investigation before following the workflow

**The specifications are authoritative.** If something doesn't match, report the discrepancy - don't try to "figure out" the actual format through exploration.

---

## Overview

Mastermind is a markdown-based framework for tracking progress across multiple projects via Claude Code session analysis. It maintains a central "vault" with project specs, session reports, and daily digests.

## Core Concepts

**Vault**: The mastermind directory containing all tracking data. Location configured in `~/.claude/mastermind.local.md`.

**Projects**: Registered directories that mastermind monitors for Claude Code session activity.

**Session Reports**: Property-based narrative reports generated from Claude Code conversation history, capturing decisions, issues, learnings, and user preferences.

**Specs**: Source-of-truth documents defining each project's purpose, scope, and direction.

## Vault Structure

```
[vault]/
├── config.yaml              # Project registry
├── state/
│   └── sync-state.yaml      # Sync tracking (last synced timestamps)
├── projects/
│   └── [project-name]/
│       ├── spec.md          # Project specification
│       ├── status.md        # Current state summary
│       └── sessions/
│           └── YYYY-MM-DD-descriptive-title.md    # Session reports
└── daily/
    └── [YYYY-MM-DD].md      # Cross-project daily digests
```

**Session filename format**: `YYYY-MM-DD-descriptive-title.md`
- Date prefix enables chronological sorting
- Descriptive title (max 10 words, hyphen-connected) summarizes the session
- Example: `2026-01-15-implementing-jwt-authentication.md`

## Available Commands

| Command | Purpose |
|---------|---------|
| `/mm:init <vault-path>` | Initialize a new vault (first-time setup) |
| `/mm:add <name> <path>` | Register a new project to monitor |
| `/mm:sync [project]` | Analyze new Claude Code sessions and generate reports |
| `/mm:overview` | Dashboard of all monitored projects |
| `/mm:status <project>` | Deep dive on one project |
| `/mm:plan [project]` | Create or update a project spec |
| `/mm:daily` | Generate today's cross-project digest |

## Getting Started

1. **Initialize vault**: `/mm:init ~/path/to/vault`
2. **Add projects**: `/mm:add my-project /path/to/project`
3. **Sync sessions**: `/mm:sync`
4. **Create specs**: `/mm:plan my-project`

## Configuration

The vault path is stored in `~/.claude/mastermind.local.md` (created by `/mm:init`):

```markdown
# Mastermind Configuration
vault: /path/to/your/mastermind/vault
```

**All commands work from any directory** - they read the vault location from this config file.

## Session Report Properties

Reports are narrative documents (like blog posts) that capture these properties when present:

- **Goal**: What the user was trying to accomplish
- **Outcome**: Success level, what was achieved
- **Decisions**: Technical/architectural choices with rationale
- **Issues & Fixes**: Problems encountered, root causes, solutions (with code quotes)
- **Frustrations**: User pain points, repeated problems
- **Preferences**: Style and approach preferences revealed
- **Significant Code**: Verbatim quotes of important code (bugs, fixes, patterns)
- **Unfinished Work**: Tasks left incomplete, deferred questions
- **Learnings**: Patterns and insights for future sessions

## Workflow

1. **Setup**: Run `/mm:init ~/your/vault` to create vault
2. **Add Projects**: Run `/mm:add <name> <path>` for each project to track
3. **Work**: Do your normal development in project directories
4. **Sync**: Periodically run `/mm:sync` (from any directory)
5. **Review**: Read session reports, update specs with `/mm:plan`
6. **Daily**: Generate cross-project digest with `/mm:daily`

For detailed specifications, see:
- `references/vault-structure.md` - Complete vault format
- `references/report-properties.md` - Session report property definitions