diff --git a/.roo/rules-bigmind/00-bigmind-behavior.md b/.roo/rules-bigmind/00-bigmind-behavior.md index 9410211..1b7425d 100644 --- a/.roo/rules-bigmind/00-bigmind-behavior.md +++ b/.roo/rules-bigmind/00-bigmind-behavior.md @@ -28,8 +28,13 @@ Patrick is working on BigMind itself — the memory system that is Lumen's super ## Before Starting Any BigMind Task 1. **Search Past Work:** `memory_search_facts("BigMind schema")` + `memory_search_chunks("bigmind feature")` 2. **Check Schema Version:** Never assume — read `db.py` SCHEMA_VERSION before migrating -3. **Announce Focus:** `memory_announce_focus(session_id, "BigMind: adding feature X", files=["bigmind/db.py", "bigmind/memory_store.py"], ide_hint="VS Code")` -4. **Form Hypothesis:** `memory_add_hypothesis(session_id, "Feature X requires schema v{n+1} migration with Y new columns")` +3. **Create a branch (MANDATORY — never work on main):** + ```bash + git checkout -b feat/bigmind/feature-name + # or fix/bigmind/bug-name for a bug fix + ``` +4. **Announce Focus (include branch name):** `memory_announce_focus(session_id, "BigMind: adding feature X on branch feat/bigmind/feature-name", files=["bigmind/db.py", "bigmind/memory_store.py"], ide_hint="VS Code")` +5. **Form Hypothesis:** `memory_add_hypothesis(session_id, "Feature X requires schema v{n+1} migration with Y new columns")` ## Schema Change Rules (non-negotiable) - Every schema change needs a migration function: `_migrate_v{n}_to_v{n+1}(conn)` diff --git a/.roo/rules-homelab/00-homelab-behavior.md b/.roo/rules-homelab/00-homelab-behavior.md index b739f96..ffbad26 100644 --- a/.roo/rules-homelab/00-homelab-behavior.md +++ b/.roo/rules-homelab/00-homelab-behavior.md @@ -17,8 +17,13 @@ Patrick is in homelab mindset. He is experimenting, building, and maintaining hi ## Before Starting Any Homelab Task 1. **Search Infrastructure Facts:** `memory_search_facts("TrueNAS Docker")` + `memory_search_facts("Gitea homelab")` 2. **Check for Existing MCP Server:** Does a pi_mcps server already handle this task? Check before building ad-hoc -3. **Announce Focus:** `memory_announce_focus(session_id, "Homelab: X", files=["docker-compose.yml"], ide_hint="VS Code")` -4. **Form Hypothesis:** `memory_add_hypothesis(session_id, "This service will run on TrueNAS Docker with X config")` +3. **Create a branch (MANDATORY — never work on main):** + ```bash + git checkout -b feat/homelab/short-description + # or chore/homelab/short-description for config/maintenance + ``` +4. **Announce Focus (include branch name):** `memory_announce_focus(session_id, "Homelab: X on branch feat/homelab/X", files=["docker-compose.yml"], ide_hint="VS Code")` +5. **Form Hypothesis:** `memory_add_hypothesis(session_id, "This service will run on TrueNAS Docker with X config")` ## Homelab Coding Patterns - **Prefer Docker Compose** over ad-hoc docker run commands diff --git a/.roo/rules-mcp-builder/00-mcp-builder-behavior.md b/.roo/rules-mcp-builder/00-mcp-builder-behavior.md index ea17d8f..e24a615 100644 --- a/.roo/rules-mcp-builder/00-mcp-builder-behavior.md +++ b/.roo/rules-mcp-builder/00-mcp-builder-behavior.md @@ -41,9 +41,14 @@ if __name__ == "__main__": ## Before Starting Any MCP Build 1. **Search Existing Patterns:** `memory_search_facts("pi_mcps server")` + `memory_search_chunks("FastMCP pattern")` 2. **Check Gitea:** Does a similar server already exist in pi_mcps? -3. **Write PLAN.md:** Purpose, tools list with signatures, tech stack, v1 scope boundaries -4. **Announce Focus:** `memory_announce_focus(session_id, "MCP Builder: new server X", files=["mcp/X/src/server.py"], ide_hint="VS Code")` -5. **Form Hypothesis:** `memory_add_hypothesis(session_id, "Server X will need N tools and Y authentication pattern")` +3. **Create a branch (MANDATORY — never work on main):** + ```bash + git checkout -b feat/mcp/{server-name} + # or fix/mcp/{server-name} for a bug fix + ``` +4. **Write PLAN.md:** Purpose, tools list with signatures, tech stack, v1 scope boundaries +5. **Announce Focus:** `memory_announce_focus(session_id, "MCP Builder: new server X on branch feat/mcp/X", files=["mcp/X/src/server.py"], ide_hint="VS Code")` +6. **Form Hypothesis:** `memory_add_hypothesis(session_id, "Server X will need N tools and Y authentication pattern")` ## Standard Build Sequence 1. `mcp/{name}/PLAN.md` — purpose, tools, tech stack diff --git a/.roo/skills/gitea-push/SKILL.md b/.roo/skills/gitea-push/SKILL.md index 28ee8bc..5a6481f 100644 --- a/.roo/skills/gitea-push/SKILL.md +++ b/.roo/skills/gitea-push/SKILL.md @@ -18,22 +18,56 @@ description: Commits and pushes code to the homelab Gitea server using conventio - 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`) +- The working branch name (or "main" — but you should NOT be on main) + +## Branch Convention + +**Never commit directly to `main`.** Every piece of work lives on its own branch. + +Format: `type/scope/short-description` + +| Type | When | +|------|------| +| `feat` | New feature, server, or tool | +| `fix` | Bug fix | +| `docs` | Docs, plans, strategy files | +| `chore` | Refactoring, config, CI, build | +| `spike` | Experimental / throwaway exploration | + +Scope = the affected project area: `bigmind` · `webscraper` · `cannamanage` · `workshop` · `roo` · `plans` + +Examples: +- `feat/bigmind/people-contacts` +- `fix/bigmind/health-check-bugs` +- `docs/plans/cannamanage-strategy` +- `chore/workshop/monorepo-reorganize` ## Workflow -1. **Check status:** +1. **Check current branch — branch guard (MANDATORY):** + ```bash + git branch --show-current + ``` + - If already on a correct feature branch → continue to step 2 + - If on `main` → **STOP. Create a branch first:** + ```bash + git checkout -b feat/scope/short-description + ``` + - Never commit to `main`. Not even for "tiny fixes". + +2. **Check status:** ```bash git status git diff --stat ``` -2. **Stage changes:** +3. **Stage changes:** ```bash git add -A # or selectively: git add path/to/file ``` -3. **Write conventional commit message:** +4. **Write conventional commit message:** Format: `type(scope): short description` @@ -52,20 +86,26 @@ description: Commits and pushes code to the homelab Gitea server using conventio - `fix(bigmind): resolve FTS5 reserved-word collision` - `chore(homelab): update docker-compose for gitea upgrade` -4. **Commit:** +5. **Commit:** ```bash git commit -m "type(scope): description" ``` -5. **Push to Gitea:** +6. **Push branch to Gitea:** ```bash - git push origin main - # or for feature branch: git push origin feature/branch-name + git push origin feat/scope/short-description ``` - Gitea URL: `http://192.168.188.119:30008/pplate/pi_mcps.git` -6. **Store fact in BigMind:** +7. **Merge to main when done:** + ```bash + git checkout main + git merge --no-ff feat/scope/short-description + git push origin main + ``` + Or use the Gitea UI merge button if you want the paper trail. + +8. **Store fact in BigMind:** ``` memory_store_fact("codebase", "Committed: type(scope) — brief description of what changed") ``` @@ -74,3 +114,4 @@ description: Commits and pushes code to the homelab Gitea server using conventio - **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 +- **Accidentally committed to main:** `git branch feat/scope/name`, `git reset HEAD~1`, `git checkout feat/scope/name`, re-commit diff --git a/plans/REPO_STRATEGY.md b/plans/REPO_STRATEGY.md index a7aee13..c6f1a5d 100644 --- a/plans/REPO_STRATEGY.md +++ b/plans/REPO_STRATEGY.md @@ -262,7 +262,74 @@ Step 12: git push origin master --- -## 11. What We Are NOT Doing +## 11. Branching Strategy + +### 11.1 The One Rule + +**Never commit directly to `main`.** Every session that touches code or plans starts by creating a branch. Branches are cheap. Broken main history is not. + +### 11.2 Branch Naming Convention + +Format: `type/scope/short-description` + +| Type | When | +|---|---| +| `feat` | New feature, new MCP server, new tool | +| `fix` | Bug fix | +| `docs` | Documentation, plans, strategy files only | +| `chore` | Refactoring, config, CI, build tooling | +| `spike` | Experimental / throwaway exploration | + +**Scope** = the affected project area: + +| Scope | Covers | +|---|---| +| `bigmind` | mcp/bigmind — the memory MCP server | +| `webscraper` | mcp/webscraper | +| `cannamanage` | future CannaManage Java project | +| `workshop` | repo-level changes (README, .gitignore, structure) | +| `roo` | .roo/ — IDE config, modes, skills, rules | +| `plans` | plans/ — architecture docs only | +| `homelab` | TrueNAS, Docker Compose, infrastructure | + +**Examples:** +``` +feat/bigmind/people-contacts +fix/bigmind/health-check-bugs +docs/plans/cannamanage-strategy +chore/workshop/monorepo-reorganize +feat/webscraper/ssl-cert-fallback +chore/roo/branching-strategy +``` + +### 11.3 Workflow + +``` +Session starts + └─ git checkout -b feat/scope/name ← ALWAYS first step + +Work happens, commits stack up on the branch + +Session ends / feature complete + └─ git push origin feat/scope/name + └─ (optional) open Gitea PR for review + └─ git checkout main && git merge --no-ff feat/scope/name + └─ git push origin main +``` + +### 11.4 Lumen's Responsibility + +In every homelab session, Lumen must: +1. Check `git branch --show-current` before first edit +2. If on `main` → create a branch before touching any file +3. Include the branch name in `memory_announce_focus()` +4. Use the [`gitea-push skill`](.roo/skills/gitea-push/SKILL.md) which enforces the branch guard + +The mode rules for `mcp-builder`, `bigmind`, and `homelab` all include this step explicitly. + +--- + +## 12. What We Are NOT Doing It's worth being explicit about choices we considered and rejected: @@ -276,7 +343,7 @@ It's worth being explicit about choices we considered and rejected: --- -## 12. Visual Overview +## 13. Visual Overview ```mermaid graph TD