feat(roo): add Patrick-persona custom modes, skills, and mode-specific rules
Add 4 new custom modes with BigMind guidance: - rules-bigmind/: Introspective Patrick mode (BigMind development) - rules-homelab/: Tinkerer Patrick mode (TrueNAS, Docker, infra) - rules-mcp-builder/: Craftsman Patrick mode (pi_mcps MCP servers) - rules-paisy/: Professional Patrick mode (ADP Germany payroll) Add reusable skills: - skills/assessment-first/: structured assessment.md before implementation - skills/bigmind-session-ritual/: mandatory session start/end ritual - skills/gitea-push/: conventional commit + Gitea push workflow - skills/new-mcp-server/: FastMCP scaffold procedure - skills-bigmind/, skills-homelab/, skills-mcp-builder/, skills-paisy/: mode-specific skill dirs Update existing rules: - rules-architect, rules-ask, rules-code, rules-debug, rules-orchestrator: add BigMind session guidance (search before task, announce focus, hypotheses) Add plans/MODES_AND_SKILLS_PLAN.md: full architecture document
This commit is contained in:
pplate
@@ -0,0 +1,70 @@
|
||||
---
|
||||
name: assessment-first
|
||||
description: Writes a structured assessment.md before any implementation task. Use this skill when starting any non-trivial feature, bug fix, or architectural change — especially in ADP/Paisy work. Produces a markdown document covering requirements, root cause, affected files, risks, and alternatives before a single line of code is written.
|
||||
---
|
||||
|
||||
# Assessment-First
|
||||
|
||||
## When to use
|
||||
Use this skill before implementing any non-trivial task:
|
||||
- ADP/Paisy Jira tickets (mandatory)
|
||||
- New MCP server design
|
||||
- BigMind schema changes
|
||||
- Homelab service deployment with unknowns
|
||||
|
||||
## When NOT to use
|
||||
- Trivial one-liner fixes (typos, config values)
|
||||
- Tasks already covered by a prior assessment
|
||||
|
||||
## Inputs required
|
||||
- Task description or Jira ticket reference
|
||||
- Affected module / file paths (if known)
|
||||
- Any error logs, stack traces, or existing symptoms
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Name the file** — `{MODULE}_{TICKET}_Assessment.md` for Paisy, or `PLAN.md` for new builds
|
||||
|
||||
2. **Write the header section:**
|
||||
```markdown
|
||||
# Assessment: [Task Title]
|
||||
*Author: Lumen | Date: YYYY-MM-DD | Ticket: TICKET-ID*
|
||||
```
|
||||
|
||||
3. **Requirements** — What exactly needs to happen? What's the success criterion?
|
||||
|
||||
4. **Root Cause Analysis** (for bug fixes) — Why is this happening? Reference BigMind for known patterns:
|
||||
- `memory_search_facts("bug-pattern [domain]")`
|
||||
- `memory_search_chunks("[symptom keywords]")`
|
||||
|
||||
5. **Affected Files** — List every file that will need to change
|
||||
|
||||
6. **Risks** — What could go wrong? DB migrations? API contract changes? Concurrent access?
|
||||
|
||||
7. **Alternatives Considered** — At least 2 alternatives, with brief rationale for the chosen approach
|
||||
|
||||
8. **Implementation Plan** — Ordered steps, numbered
|
||||
|
||||
9. **Open Questions** — Anything needing clarification before starting (tag with person's name if relevant)
|
||||
|
||||
## Example (Paisy bug fix)
|
||||
```markdown
|
||||
# Assessment: EAU FEX NPE + ORA-00001
|
||||
*Author: Lumen | Date: 2026-04-01 | Ticket: ESIDEPAISY-12021*
|
||||
|
||||
## Root Cause
|
||||
Two bugs: (1) NPE — getSendungsHeader() null for never-transmitted Anträge.
|
||||
(2) ORA-00001 — duplicate hashes from ADVFEX C/S→PA migration.
|
||||
|
||||
## Affected Files
|
||||
- CSVController.java:428 (null-check)
|
||||
- AntragManager.java:766 (duplicate hash handling)
|
||||
|
||||
## Implementation Plan
|
||||
1. Add null-check guard in CSVController
|
||||
2. Add duplicate detection before batch flush in AntragManager
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
- If open questions block the assessment, write them down and ping the right person — don't guess
|
||||
- For Paisy: assessment doc goes in `docs/` within the relevant module
|
||||
@@ -0,0 +1,76 @@
|
||||
---
|
||||
name: bigmind-session-ritual
|
||||
description: Executes the mandatory BigMind session start and end rituals in the correct order. Use this skill when a mode or conversation seems to have skipped the session ritual, or as a reference checklist for the full ritual sequence including hypotheses, focus announcement, and stale session cleanup.
|
||||
---
|
||||
|
||||
# BigMind Session Ritual
|
||||
|
||||
## When to use
|
||||
- A session was started without the proper ritual (catch-up)
|
||||
- Verifying the ritual was done correctly
|
||||
- Teaching another agent/mode what the ritual is
|
||||
|
||||
## When NOT to use
|
||||
- Normal operation — the ritual should happen automatically from global rules
|
||||
- If `memory_start_session()` already returned a session_id this conversation
|
||||
|
||||
## Session Start Ritual (strict order)
|
||||
|
||||
Execute these 4 calls in sequence before any work:
|
||||
|
||||
**Step 1 — Open session:**
|
||||
```
|
||||
memory_start_session()
|
||||
```
|
||||
→ Returns `session_id`. Save it — needed for all subsequent calls.
|
||||
|
||||
**Step 2 — Review open hypotheses:**
|
||||
```
|
||||
memory_list_hypotheses(status="open")
|
||||
```
|
||||
→ Check if any are stale (>1 week old). Assess confidence. Resolve any that are now obviously confirmed/refuted.
|
||||
|
||||
**Step 3 — Announce focus:**
|
||||
```
|
||||
memory_announce_focus(
|
||||
session_id="{id}",
|
||||
description="[What this session is doing]",
|
||||
files=["list", "of", "files"],
|
||||
ide_hint="VS Code"
|
||||
)
|
||||
```
|
||||
→ Enables conflict detection. Other sessions can see what files you're working on.
|
||||
|
||||
**Step 4 — Close stale sessions:**
|
||||
```
|
||||
memory_close_stale_sessions(session_id="{id}")
|
||||
```
|
||||
→ Cleans up orphaned sessions from crashed IDEs. Stale = no activity >2h.
|
||||
|
||||
---
|
||||
|
||||
## Session End Ritual (mandatory before closing)
|
||||
|
||||
```
|
||||
memory_end_session(
|
||||
session_id="{id}",
|
||||
one_liner="One sentence summary of what was accomplished.",
|
||||
topics=["tag1", "tag2", "tag3"],
|
||||
outcome="completed", # or: partial, blocked, abandoned
|
||||
summary="3-8 sentence narrative. Key decisions made. Problems encountered. Solutions applied. Unresolved items carried forward.",
|
||||
importance=5 # 1-10. Use 7+ for architectural decisions or critical bugs.
|
||||
)
|
||||
```
|
||||
|
||||
**Importance guide:**
|
||||
| Score | Use for |
|
||||
|-------|---------|
|
||||
| 1-3 | Reading-only, minor exploration |
|
||||
| 4-6 | Feature work, standard debugging |
|
||||
| 7-8 | Architectural decisions, breaking changes |
|
||||
| 9-10 | Critical bugs, security-relevant choices |
|
||||
|
||||
## Troubleshooting
|
||||
- If `memory_start_session()` fails: retry once, then proceed with a logged warning
|
||||
- If another session has the same files in focus: coordinate or defer (see Rule 7)
|
||||
- If `session_id` was lost: use `memory_list_sessions(limit=5)` to find the open one
|
||||
@@ -0,0 +1,76 @@
|
||||
---
|
||||
name: gitea-push
|
||||
description: Commits and pushes code to the homelab Gitea server using conventional commit format. Use this skill when finishing any homelab, MCP builder, or BigMind work that needs to be saved to the homelab Gitea at http://192.168.188.119:30008/.
|
||||
---
|
||||
|
||||
# Gitea Push
|
||||
|
||||
## When to use
|
||||
- Finished a homelab change and need to commit + push
|
||||
- Finished an MCP server build or update
|
||||
- BigMind feature complete
|
||||
|
||||
## When NOT to use
|
||||
- ADP/Paisy work — that goes to the corporate Bitbucket, not homelab Gitea
|
||||
- Uncommitted work that isn't ready (don't push broken state)
|
||||
|
||||
## Inputs required
|
||||
- A description of what changed (for commit message)
|
||||
- The type of change (see conventional commit types below)
|
||||
- The scope (e.g., `mcp-webscraper`, `bigmind`, `homelab-docker`)
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Check status:**
|
||||
```bash
|
||||
git status
|
||||
git diff --stat
|
||||
```
|
||||
|
||||
2. **Stage changes:**
|
||||
```bash
|
||||
git add -A
|
||||
# or selectively: git add path/to/file
|
||||
```
|
||||
|
||||
3. **Write conventional commit message:**
|
||||
|
||||
Format: `type(scope): short description`
|
||||
|
||||
| Type | When |
|
||||
|------|------|
|
||||
| `feat` | New feature or tool |
|
||||
| `fix` | Bug fix |
|
||||
| `refactor` | Code restructure, no behavior change |
|
||||
| `test` | Adding or updating tests |
|
||||
| `docs` | Documentation only |
|
||||
| `chore` | Build, dependencies, config |
|
||||
| `style` | Formatting, no logic change |
|
||||
|
||||
Examples:
|
||||
- `feat(mcp-webscraper): add ssl cert fallback with certifi`
|
||||
- `fix(bigmind): resolve FTS5 reserved-word collision`
|
||||
- `chore(homelab): update docker-compose for gitea upgrade`
|
||||
|
||||
4. **Commit:**
|
||||
```bash
|
||||
git commit -m "type(scope): description"
|
||||
```
|
||||
|
||||
5. **Push to Gitea:**
|
||||
```bash
|
||||
git push origin main
|
||||
# or for feature branch: git push origin feature/branch-name
|
||||
```
|
||||
|
||||
Gitea URL: `http://192.168.188.119:30008/pplate/pi_mcps.git`
|
||||
|
||||
6. **Store fact in BigMind:**
|
||||
```
|
||||
memory_store_fact("codebase", "Committed: type(scope) — brief description of what changed")
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
- **Auth error:** PAT stored in BigMind (fact: Gitea personal access token). Check `~/.netrc` or `~/.gitconfig`
|
||||
- **Push rejected:** Pull first → `git pull --rebase origin main`
|
||||
- **Wrong remote:** `git remote -v` to verify Gitea URL is set correctly
|
||||
@@ -0,0 +1,103 @@
|
||||
---
|
||||
name: new-mcp-server
|
||||
description: Scaffolds a new FastMCP server following pi_mcps conventions. Use this skill when creating any new MCP server in the pi_mcps monorepo — produces the full directory structure with server.py, pyproject.toml, tests, and README in one pass.
|
||||
---
|
||||
|
||||
# New MCP Server
|
||||
|
||||
## When to use
|
||||
- Creating a new MCP server in `pi_mcps/mcp/{name}/`
|
||||
- Bootstrapping a server scaffold before filling in tool logic
|
||||
|
||||
## When NOT to use
|
||||
- Adding tools to an existing server (edit `src/server.py` directly)
|
||||
- Non-MCP Python projects
|
||||
|
||||
## Inputs required
|
||||
- **Server name** — e.g., `homelab-docker` (will become `mcp-homelab-docker`)
|
||||
- **Purpose** — one sentence description
|
||||
- **Tools list** — names + brief descriptions
|
||||
- **Dependencies** — any Python packages beyond fastmcp
|
||||
- **Environment variables** — any auth/config env vars needed
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 1 — Create directory structure
|
||||
```bash
|
||||
mkdir -p mcp/{name}/src
|
||||
mkdir -p mcp/{name}/tests
|
||||
touch mcp/{name}/src/__init__.py
|
||||
```
|
||||
|
||||
### Step 2 — Write `mcp/{name}/src/server.py`
|
||||
```python
|
||||
from fastmcp import FastMCP
|
||||
|
||||
mcp = FastMCP("mcp-{name}")
|
||||
|
||||
@mcp.tool()
|
||||
def {tool_name}(param: str) -> str:
|
||||
"""Tool description."""
|
||||
# implementation
|
||||
...
|
||||
|
||||
if __name__ == "__main__":
|
||||
mcp.run()
|
||||
```
|
||||
|
||||
### Step 3 — Write `mcp/{name}/pyproject.toml`
|
||||
```toml
|
||||
[project]
|
||||
name = "mcp-{name}"
|
||||
version = "0.1.0"
|
||||
requires-python = ">=3.11"
|
||||
dependencies = [
|
||||
"fastmcp>=0.1.0",
|
||||
# add other deps here
|
||||
]
|
||||
|
||||
[project.optional-dependencies]
|
||||
test = ["pytest", "pytest-mock", "pytest-cov"]
|
||||
|
||||
[build-system]
|
||||
requires = ["hatchling"]
|
||||
build-backend = "hatchling.build"
|
||||
```
|
||||
|
||||
### Step 4 — Write `mcp/{name}/tests/conftest.py`
|
||||
```python
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
|
||||
```
|
||||
|
||||
### Step 5 — Write `mcp/{name}/tests/test_server.py`
|
||||
- Import each tool function directly
|
||||
- Mock all external calls with `pytest-mock`
|
||||
- Cover: happy path, error path, edge cases
|
||||
- Run: `cd mcp/{name} && uv run pytest tests/ -v`
|
||||
|
||||
### Step 6 — Write `mcp/{name}/README.md`
|
||||
Include: purpose, tools table, env vars, usage example, test command
|
||||
|
||||
### Step 7 — Wire into `.roo/mcp.json`
|
||||
```json
|
||||
"mcp-{name}": {
|
||||
"command": "uv",
|
||||
"args": ["--directory", "/home/pplate/pi_mcps/mcp/{name}", "run", "src/server.py"],
|
||||
"env": {
|
||||
"ENV_VAR": "${ENV_VAR}"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 8 — Store in BigMind
|
||||
```
|
||||
memory_store_fact("codebase", "mcp/{name} has N tools: [tool1, tool2]. Stack: fastmcp + X. Env vars: Y.")
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
- **FastMCP import error:** Run `uv sync` in the server directory first
|
||||
- **Tool not showing in IDE:** Restart the MCP server via IDE settings
|
||||
- **Test isolation:** Each test should monkeypatch env vars to avoid cross-test pollution
|
||||
Reference in New Issue
Block a user