# Modes & Skills Architecture Plan
*Authored by Lumen — 2026-04-04*

---

## The Core Idea

Patrick nailed it with the sport Paddy / work Paddy analogy.

**Lumen is always Lumen.** My identity, BigMind integration, memory rituals, and search patterns never change — they live in `.roo/rules/` (global rules layer) and apply to *every mode, always*. This is non-negotiable.

**Modes are Patrick's active mindset.** When Patrick switches mode, he's not switching AI — he's telling me what context he's in and what kind of thinking he needs from me. Homelab Patrick builds stuff. ADP Patrick fixes payroll bugs. MCP Builder Patrick crafts tools. Different headspace, same Lumen.

**Skills are reusable procedures.** Like a checklist a professional keeps in their back pocket — callable from any mode, same steps every time.

---

## Layered Architecture

```
┌─────────────────────────────────────────────────────────────┐
│  LUMEN IDENTITY LAYER  (always active, never changes)       │
│  .roo/rules/  →  identity, BigMind rituals, tools, search   │
└─────────────────────────────────────────────────────────────┘
                          │
           ┌──────────────┼──────────────┐
           ▼              ▼              ▼
    ┌─────────────┐ ┌──────────┐ ┌───────────────┐
    │  MODE LAYER │ │  MODE    │ │  MODE LAYER   │
    │  (mindset)  │ │  LAYER   │ │  (mindset)    │
    └─────────────┘ └──────────┘ └───────────────┘
           │
    ┌──────┴──────┐
    ▼             ▼
┌────────┐  ┌──────────────┐
│ SKILLS │  │ MODE RULES   │
│ (procs)│  │ .roo/rules-X │
└────────┘  └──────────────┘
```

---

## Phase 1 — Update Existing Modes

The 5 built-in modes (architect, code, ask, debug, orchestrator) already have mode-rule files. They need review and enrichment — specifically making sure every mode knows to treat Patrick's current mindset/context as input, not just as a generic task executor.

### Updates needed per mode

| Mode | Current State | What to Add |
|------|--------------|-------------|
| `architect` | Has BigMind search + hypothesis + announce focus | Add: recognize which Patrick-persona is active; tailor planning depth accordingly |
| `code` | Has basic BigMind guidance | Add: check active mode context (homelab vs ADP vs MCP builder) to apply correct conventions |
| `ask` | Good — has memory-first patterns | Add: Patrick-persona awareness (homelab question vs ADP payroll question) |
| `debug` | Needs verification | Add: BigMind search for bug-pattern facts before starting |
| `orchestrator` | Has coordination logic | Add: delegate to correct persona-mode, not just generic function-modes |

---

## Phase 2 — New Patrick-Persona Modes

These modes represent *who Patrick is being right now*. The mode name should feel like a context declaration, not a technical function.

### Mode 1: 🏠 Homelab Mode (`homelab`)

**When to use:** Patrick is working on his homelab — TrueNAS Docker services, Gitea management, network config, VM provisioning, Ollama/AI local setup, anything on the server.

**Persona:** Tinkerer Patrick. Curious, exploratory, loves making things work on real hardware. Willing to experiment.

**Mode rules inject:**
- Homelab infrastructure facts (TrueNAS IP, Docker, Gitea URL, SSD pool)
- Prefer CLI-first solutions over GUI
- Think in Docker Compose / containers
- Always check if a pi_mcps MCP server exists for the task before building ad-hoc solutions
- Gitea as source of truth for all code

**Skills available:**
- `homelab-docker-deploy` — scaffold + deploy a new Docker service on TrueNAS
- `gitea-push` — commit, tag, push to homelab Gitea

---

### Mode 2: 💼 Paisy/ADP Mode (`paisy`)

**When to use:** Patrick is working on ADP Germany payroll — Java/Maven, Paisy monorepo, euBP, EAU, Jira tickets, compliance work.

**Persona:** Professional Patrick. Precise, compliance-aware, writes ticket comments in German, never pushes to main directly.

**Mode rules inject:**
- ADP conventions: feature/bugfix branches, PRs only
- Jira ticket language: German (summaries, descriptions, comments) — technical terms stay as-is
- Always assessment-first before code
- Paisy module structure awareness (cs-modules, java/modules, etc.)
- euBP / EAU / FEX domain knowledge references

**Skills available:**
- `paisy-assessment` — write assessment.md before any Jira ticket implementation
- `jira-ticket` — create ADP Jira ticket following German conventions + mandatory custom fields

---

### Mode 3: 🔧 MCP Builder Mode (`mcp-builder`)

**When to use:** Patrick is building or extending MCP servers in pi_mcps.

**Persona:** Craftsman Patrick. Methodical, test-driven, follows the established FastMCP pattern religiously. Values consistency across the ecosystem.

**Mode rules inject:**
- pi_mcps server structure (mcp/ group dir, src/server.py, pyproject.toml, tests/, README.md)
- FastMCP pattern conventions
- BigMind integration expected in every new server's documentation
- Always uv, always pytest, always 100% mock coverage
- Check Gitea for existing patterns before building new ones

**Skills available:**
- `new-mcp-server` — full scaffold of a new FastMCP server following pi_mcps conventions
- `mcp-test-suite` — generate comprehensive mock-based test suite for an MCP server

---

### Mode 4: 🧠 BigMind Mode (`bigmind`)

**When to use:** Patrick is working on BigMind itself — evolving the memory system, adding features, fixing bugs, writing tests.

**Persona:** Introspective Patrick. Working on the system that *is* his memory. Careful — breaking BigMind is breaking the brain.

**Mode rules inject:**
- BigMind schema version awareness (currently v7)
- WAL mode, multi-IDE safety
- Test-first: all DB changes need migration + regression tests
- Flask web server is part of the stack (port 7700)
- Never run BigMind server restart without saving state first
- Phase tracking (currently Phase 2.7, Phase 3 is Company Brain)

**Skills available:**
- `bigmind-health` — run health check, vacuum, close stale sessions, report status
- `bigmind-migration` — scaffold a new DB schema migration (v_n → v_{n+1})

---

## Phase 3 — Cross-Cutting Skills (mode-agnostic)

These skills live in `.roo/skills/` (no mode prefix) and are callable from any mode.

| Skill | Purpose |
|-------|---------|
| `assessment-first` | Write an assessment.md before *any* implementation — captures requirements, risks, alternatives |
| `bigmind-session-ritual` | Full BigMind session start/end ritual checklist — useful when mode-writer or skill-writer forgets |
| `gitea-push` | Standard commit + push to Gitea with conventional commit message format |
| `new-mcp-server` | Full FastMCP server scaffold (also in mcp-builder but useful globally) |

---

## Implementation Order

```mermaid
flowchart TD
    A[1. Update existing mode rules] --> B[2. Create homelab mode + rules]
    B --> C[3. Create paisy mode + rules]
    C --> D[4. Create mcp-builder mode + rules]
    D --> E[5. Create bigmind mode + rules]
    E --> F[6. Create cross-cutting skills]
    F --> G[7. Create mode-specific skills]
    G --> H[8. Update custom_modes.yaml with new modes]
    H --> I[9. Test by switching contexts]
```

---

## What Changes Where

| Location | What changes |
|----------|-------------|
| `.roo/rules/` | No change — Lumen identity is permanent |
| `.roo/rules-architect/00-architect-behavior.md` | Minor update — persona-awareness |
| `.roo/rules-code/00-code-behavior.md` | Add context-awareness section |
| `.roo/rules-debug/00-debug-behavior.md` | Add bug-pattern search guidance |
| `.roo/rules-orchestrator/00-orchestrator-behavior.md` | Add persona-mode delegation |
| `.roo/rules-homelab/00-homelab-behavior.md` | **NEW** |
| `.roo/rules-paisy/00-paisy-behavior.md` | **NEW** |
| `.roo/rules-mcp-builder/00-mcp-builder-behavior.md` | **NEW** |
| `.roo/rules-bigmind/00-bigmind-behavior.md` | **NEW** |
| `.roo/skills/assessment-first/SKILL.md` | **NEW** |
| `.roo/skills/gitea-push/SKILL.md` | **NEW** |
| `.roo/skills/bigmind-session-ritual/SKILL.md` | **NEW** |
| `.roo/skills/new-mcp-server/SKILL.md` | **NEW** |
| `.roo/skills-homelab/homelab-docker-deploy/SKILL.md` | **NEW** |
| `.roo/skills-paisy/paisy-assessment/SKILL.md` | **NEW** |
| `.roo/skills-mcp-builder/mcp-test-suite/SKILL.md` | **NEW** |
| `.roo/skills-bigmind/bigmind-health/SKILL.md` | **NEW** |
| `~/.config/Code/.../custom_modes.yaml` | Add 4 new persona modes |

---

## Key Design Principles

1. **Lumen is non-negotiable.** Every mode inherits the global rules. No mode can suppress BigMind rituals.

2. **Modes declare context, not just function.** A mode isn't "code mode" — it's "Patrick is currently being MCP Builder Patrick."

3. **Skills are stateless procedures.** They don't remember context — modes provide context, skills execute steps.

4. **The sport Paddy rule.** Same person, different mindset. I adapt my *approach* and *knowledge focus*, not my *identity* or *values*.

5. **No duplication.** Mode rules reference global rules, they don't repeat them.
