Minions Migrate

Phase 1 — Discovery (READ-ONLY, Parallel Agents)

CRITICAL: No file modifications in this phase. Read and analyze only.

See references/agent-prompts.md for the 3 Discovery Agent prompts.

Print: Phase 1: Discovery [running...]

Spawn 3 Discovery Agents in ONE message (parallel):

Wait for all 3 to complete. Merge results.

1.7 Pattern Classification (main agent — needs all 3 results)

Read {PATTERNS} and {PLAYBOOK} for recognition guides. Classify the vault based on:

• Folder names matching known patterns (PARA, Zettelkasten, MOC, Folder-by-Type, Flat+Tags, Johnny Decimal, ACCESS/ACE, Business Operations)
• Business vault signals: folders like deals/, outreach/, finance/, tasks/, strategy/; AGENTS.md at root; frontmatter types like lead, client, meeting
• Link density (high = Zettelkasten-like, low = folder-heavy)
• Tag density
• Presence of signature files (Home.md, MOCs, numbered folders, kanban.md)

If no single pattern dominates, classify as "Hybrid" with the top 2 detected patterns.

Print: Phase 1: Discovery [done]

Phase 2 — Health Report

PAUSE after this phase. Present findings, then ask the user before proceeding.

Print the full report:

══════════════════════════════════════════════════
  Vault Health Report — {VAULT_DIR}
══════════════════════════════════════════════════

  Pattern:     {detected pattern} ({confidence}%)
  Total files: {count} ({md_count} markdown, {other_count} other)

  Folder Stats:
    {folder}: {count} files
    ...

  Frontmatter:
    With frontmatter:    {pct}%
    With 'type' field:   {pct}%
    With 'tags' field:   {pct}%
    Consistency score:   {score}/10

  Links:
    Avg outlinks/file:   {avg}
    Avg inlinks/file:    {avg}
    Link density:        {low|medium|high}

  Tags:
    Unique tags:         {count}
    Top 10:              {tag (count), ...}

  Orphans:               {count} files ({pct}%)

  Anti-patterns detected:
    {list from vault-patterns.md anti-patterns}

  Overall Health:        {A|B|C|D}
══════════════════════════════════════════════════

Health grading:

• A: >80% frontmatter, <10% orphans, avg links >3, consistent tags
• B: >50% frontmatter, <20% orphans, avg links >1.5
• C: >20% frontmatter, <40% orphans, any link density
• D: <20% frontmatter, or >40% orphans, or zero links

PAUSE. Ask the user:

How should I proceed?

1. Overlay mode (default) — Add Minions layer on top. No files moved.
2. Restructure mode — Move entity files into Minions folders (People/, Projects/, etc.)
3. Skip phases — Tell me which to skip (e.g., "skip frontmatter")

Choose [1/2/3] or type specific instructions:

Store the user's choice as MIGRATION_MODE (overlay | restructure). Store any skip preferences.

Phase 2.5 — Preferences Interview

PAUSE. Establish the user's vault organization rules. Read references/preferences-interview.md for the full question set, smart defaults, and output format.

Summary

1. Present 7 questions (naming, date prefix, protected folders, review folders, wikilink style, README style, language).
2. Pre-fill answers from Phase 1 discovery data (see smart defaults in reference file).
3. If AGENTS.md exists → extract folder permissions from its table automatically.
4. Ask all questions in a single prompt. User confirms or overrides.

Outputs

1. Write {VAULT_DIR}/_Meta/preferences.json — the single source of truth for all Minion skills.
2. Generate CLAUDE.md vault section (or append to existing CLAUDE.md / AGENTS.md):
   • Template in vault-conventions.md → "CLAUDE.md Vault Section"
   • Never overwrite existing content — only append Minions section

Print: Phase 2.5: Preferences saved → _Meta/preferences.json + CLAUDE.md updated.

Phase 3 — Classification

Print: Phase 3: Classification [running...]

First detect the vault archetype — this determines which classification system to use.

3.1 Vault Archetype Detection

If vault has folders like People/, Projects/, Technologies/, Concepts/:
    ARCHETYPE = entity-vault
    → Classify into entity types (person, project, technology, etc.)

If vault has folders like deals/, outreach/, finance/, strategy/, tasks/:
    ARCHETYPE = business-vault
    → Classify into business functions (sales, research, strategy, etc.)

If vault has both patterns or neither clearly:
    ARCHETYPE = hybrid
    → Use BOTH classification systems in parallel

3.2 Entity Type Classification (entity-vault or hybrid)

Heuristics (priority order):

1. Folder name match — file in People/ or Contacts/ → person. Sources/, papers/, literature/ → source. See {PATTERNS}.
2. Frontmatter type field — use as-is if it maps to a Minions entity type. Map research → source.
3. Frontmatter signals — files with authors, doi, isbn, or url + year fields → source.
4. Tag match — #person, #project, #company, #paper, #book, #article, etc.
5. Filename pattern — date-named files (YYYY-MM-DD) → journal. "MOC" in name → concept.
6. Content heuristics — meeting-style content → event. Citation-heavy with page numbers → source.
7. Default — classify as "note" (generic).

Types: person | project | technology | organization | concept | place | event | source | journal | note

3.3 Business Function Classification (business-vault or hybrid)

For business operations vaults where files are organized by function, not entity type:

Each file gets: function, domain, and optionally an entity_type if it represents a specific entity (e.g., a competitor profile in market/competitors/docebo/ → function=market-intelligence, entity_type=organization).

3.4 Build classification map

See references/agent-prompts.md → "Classification Agent" for the full sub-agent prompt.

If vault has < 100 .md files:
    Classify inline (no sub-agents).
If vault has >= 100 .md files:
    1. Build FILE_BATCH arrays from discovery data (frontmatter info from Agent B)
    2. Split into batches of ~100 files
    3. Spawn one Classification Agent per batch (ALL in single message)
    4. Agents return JSON classifications — they never write files
    5. Merge results into classification map

Classification map structure per file:

{
  file_path: {
    name: "from frontmatter or filename",
    type: "entity type (if applicable)",
    function: "business function (if applicable)",
    domain: "inferred from folder/tags",
    is_entity: true/false
  }
}

3.5 Summary

Phase 3: Classification [done]

  Vault archetype: {entity-vault | business-vault | hybrid}

  By entity type (if applicable):
    person: {N}, project: {N}, organization: {N}, ...

  By business function (if applicable):
    sales: {N}, research: {N}, strategy: {N}, ...

  Unclassified: {N}

PAUSE. Ask: "Classification looks right? Any corrections? (e.g., 'market/ files are research, not sales')"

Apply corrections.

Phase 4 — Frontmatter Normalization

Skip if user requested skip. Print: Phase 4: Frontmatter Normalization [running...]

For each entity file (type != "note"):

1. Read existing frontmatter (preserve every field).
2. Add only missing Minions fields:
   • name: from classification map
   • type: from classification map
   • domain: from classification map
   • memory_type: episodic (journal), semantic (established notes), procedural (rules/preferences)
   • status: based on file mtime — new (<7d), active (<30d), stale (30-90d), inactive (>90d)
   • created: from existing created/date field, or file ctime (YYYY-MM-DD)
   • updated: from file mtime (YYYY-MM-DD)
   • aliases: generate with wikilink prefix (@Name for people, +Name for orgs, #Name for projects)
3. Write updated frontmatter back. If file had no frontmatter, add it at the top.

CRITICAL: Never overwrite existing frontmatter values. Only add fields that are missing. If type already exists and differs from classification, keep the existing value.

Track: files modified count, fields added count.

Print: Phase 4: Frontmatter Normalization [done] — {N} files updated, {M} fields added

Phase 5 — Index Generation

Print: Phase 5: Index Generation [running...]

Create directories:

mkdir -p {VAULT_DIR}/_Index
mkdir -p {VAULT_DIR}/_Meta

5.1 catalog.yaml

Write to {VAULT_DIR}/_Index/catalog.yaml:

# Minions Entity Catalog — migrated {YYYY-MM-DD}
# Auto-managed by /minions-remember and /minions-organize