mcp: project-plan — herbylab Project Management
This commit is contained in:
Lovebug MCP
parent
cb688cedd4
commit
b168f1cc07
174
Sources/Homelab/herbylab-project-management.md
Normal file
174
Sources/Homelab/herbylab-project-management.md
Normal file
@ -0,0 +1,174 @@
|
||||
---
|
||||
created: '2026-05-11'
|
||||
path: Sources/Homelab
|
||||
project: herbylab-project-management
|
||||
status: active
|
||||
tags:
|
||||
- mcp
|
||||
- automation
|
||||
- n8n
|
||||
- obsidian
|
||||
type: project-plan
|
||||
updated: '2026-05-11'
|
||||
---
|
||||
|
||||
## Goal
|
||||
|
||||
Extend `herbylab` MCP to manage projects and notes as first-class artifacts backed by Postgres, with Trello as the visual projection. Vault remains the immutable content store in Phase 1; Postgres becomes sole source in a later phase.
|
||||
|
||||
Solves the pain of status hygiene and project visibility — 44+ vault entries, almost all flagged `active`, no aggregate view, no real query surface, frontmatter status edits feel wrong.
|
||||
|
||||
## Locked Decisions
|
||||
|
||||
**Three-layer model.** Mirrors Trellis:
|
||||
- Vault md files — content, narrative, immutable. Feeds wiki-vault.
|
||||
- Postgres (`herbylab` schema) — state, metadata, queryable index.
|
||||
- Trello — visual projection of project state. Read-mostly.
|
||||
|
||||
**Single MCP, not split.** Project tools live alongside vault tools in `herbylab`. One connector, one tool surface.
|
||||
|
||||
**Polymorphic tool shape.** `create_artifact(kind, ...)` and `update_artifact(kind, slug, ...)` dispatch on `kind`. Adds future artifact types without growing the tool surface.
|
||||
|
||||
**Postgres co-located with Trellis.** Same instance, separate schema (`herbylab.*`). Trellis's schema-namespace pattern leaves room for this by design.
|
||||
|
||||
**Phase 1: dual-write, immutable entries.**
|
||||
- `create_artifact` writes Postgres row + vault file atomically.
|
||||
- No content updates via MCP — entries immutable once created.
|
||||
- `update_artifact` only mutates metadata (status, tags, title, summary, domain).
|
||||
- Vault stays the read surface for Obsidian and wiki-vault.
|
||||
- New phases/addenda get new files, matching existing pattern (`ob1-deployment` + `ob1-main-deployment`).
|
||||
|
||||
**Phase N: vault retires, Postgres becomes sole source.**
|
||||
- Viewer TBD — wiki-vault adaptation or new web UI served from Postgres.
|
||||
- Out of scope for this plan.
|
||||
|
||||
**Source of truth for status: Postgres.** Status changes mid-conversation via `update_artifact` — never a file edit.
|
||||
|
||||
**Status propagates via NOTIFY → n8n → Trello.** Postgres trigger fires `pg_notify('project_changed', ...)` on insert/update. n8n LISTENs, projects to Trello.
|
||||
|
||||
**Frontmatter scope simplifies.** Vault frontmatter holds identity (`project`, `type`, `path`, `tags`, `created`). Status and `updated` leave frontmatter — Postgres concerns.
|
||||
|
||||
## Schema (Phase 1)
|
||||
|
||||
```sql
|
||||
CREATE SCHEMA herbylab;
|
||||
|
||||
CREATE TYPE herbylab.artifact_kind AS ENUM ('note', 'project');
|
||||
CREATE TYPE herbylab.project_status AS ENUM ('active', 'paused', 'blocked', 'completed', 'archived');
|
||||
CREATE TYPE herbylab.project_domain AS ENUM ('homelab', 'dev', 'venture', 'reference');
|
||||
|
||||
CREATE TABLE herbylab.artifacts (
|
||||
slug TEXT NOT NULL,
|
||||
kind herbylab.artifact_kind NOT NULL,
|
||||
title TEXT NOT NULL,
|
||||
domain herbylab.project_domain,
|
||||
tags TEXT[] DEFAULT '{}',
|
||||
vault_path TEXT NOT NULL,
|
||||
body TEXT NOT NULL,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
PRIMARY KEY (kind, slug)
|
||||
);
|
||||
|
||||
CREATE TABLE herbylab.projects (
|
||||
slug TEXT PRIMARY KEY,
|
||||
status herbylab.project_status NOT NULL DEFAULT 'active',
|
||||
summary TEXT,
|
||||
trello_card_id TEXT,
|
||||
FOREIGN KEY (kind, slug) REFERENCES herbylab.artifacts (kind, slug)
|
||||
DEFERRABLE INITIALLY DEFERRED
|
||||
);
|
||||
|
||||
CREATE INDEX idx_artifacts_kind ON herbylab.artifacts(kind);
|
||||
CREATE INDEX idx_artifacts_tags ON herbylab.artifacts USING GIN(tags);
|
||||
CREATE INDEX idx_projects_status ON herbylab.projects(status);
|
||||
```
|
||||
|
||||
`body` stores the markdown blob. Vault file holds the same content. Dual-write keeps them in lockstep; immutability eliminates drift risk.
|
||||
|
||||
## NOTIFY trigger
|
||||
|
||||
```sql
|
||||
CREATE OR REPLACE FUNCTION herbylab.notify_project_change() RETURNS TRIGGER AS $$
|
||||
DECLARE payload JSON;
|
||||
BEGIN
|
||||
payload := json_build_object(
|
||||
'op', TG_OP,
|
||||
'slug', COALESCE(NEW.slug, OLD.slug),
|
||||
'status', COALESCE(NEW.status, OLD.status)
|
||||
);
|
||||
PERFORM pg_notify('project_changed', payload::text);
|
||||
RETURN NEW;
|
||||
END;
|
||||
$$ LANGUAGE plpgsql;
|
||||
|
||||
CREATE TRIGGER projects_notify
|
||||
AFTER INSERT OR UPDATE OR DELETE ON herbylab.projects
|
||||
FOR EACH ROW EXECUTE FUNCTION herbylab.notify_project_change();
|
||||
```
|
||||
|
||||
## Tool surface
|
||||
|
||||
**Vault tools (existing, unchanged):**
|
||||
- `save_vault_note`
|
||||
- `get_vault_project`
|
||||
- `check_vault_file`
|
||||
- `list_vault_projects`
|
||||
- `get_vault_schema`
|
||||
|
||||
**Artifact tools (new):**
|
||||
- `create_artifact(kind, slug, title, vault_path, content, domain?, tags?, summary?)` — writes Postgres row + vault file. For `kind="project"`, also inserts `projects` row with default `status='active'`.
|
||||
- `update_artifact(kind, slug, **fields)` — mutates metadata only (status, title, tags, summary, domain). Never touches body or vault file.
|
||||
- `get_artifact(kind, slug)` — returns row + linked file path.
|
||||
- `list_artifacts(kind?, status?, domain?, tag?)` — filtered query.
|
||||
|
||||
`list_vault_projects` deprecates in favor of `list_artifacts` once cutover completes.
|
||||
|
||||
## Open Items
|
||||
|
||||
- [ ] Postgres deployment shape — depends on Trellis decision (LXC vs container)
|
||||
- [ ] Migration tooling — match whatever Trellis lands on
|
||||
- [ ] Trello board layout — single board with status lists vs board per domain
|
||||
- [ ] Duplicate cleanup before backfill: `ob1-deployment` + `ob1-main-deployment`, `editor-stack-upgrade` (Homelab + Venture), `content-hub-phase5-architecture` + `-planning`
|
||||
- [ ] Naming pin-down: memory has both `herbylab` and `herby-dev` — settle on one
|
||||
|
||||
## Phases
|
||||
|
||||
### Phase 1 — Infrastructure
|
||||
- [ ] Postgres instance available with `herbylab` schema on the Trellis-shared instance
|
||||
- [ ] Migration tooling chosen (match Trellis decision)
|
||||
- [ ] Apply schema, types, indexes, NOTIFY trigger
|
||||
|
||||
### Phase 2 — MCP tools
|
||||
- [ ] `create_artifact` (dual-write, transactional)
|
||||
- [ ] `update_artifact` (metadata only)
|
||||
- [ ] `get_artifact`, `list_artifacts` (read paths)
|
||||
- [ ] Tag normalization mirroring Trellis pattern
|
||||
|
||||
### Phase 3 — Trello projection
|
||||
- [ ] Trello board structure: lists for `active`, `paused`, `blocked`, `completed`. Labels for domain.
|
||||
- [ ] n8n workflow: Postgres LISTEN node on `project_changed`
|
||||
- [ ] Branch on op: INSERT → create card, UPDATE → move/edit card, DELETE → archive
|
||||
- [ ] Store `trello_card_id` back to `projects` row on creation
|
||||
|
||||
### Phase 4 — Backfill and cutover
|
||||
- [ ] Script walks existing vault project-plan files, populates `artifacts` + `projects` rows
|
||||
- [ ] Status defaults to current frontmatter value (42 of 44 are `active`)
|
||||
- [ ] Manual triage pass in Trello — drag to honest columns
|
||||
- [ ] Strip `status` / `updated` from vault frontmatter going forward
|
||||
- [ ] Backfill of existing frontmatter optional
|
||||
|
||||
### Phase N — Vault retirement
|
||||
- Deferred. Revisit once Phase 1–4 are operational and read patterns are clearer.
|
||||
|
||||
## Notes
|
||||
|
||||
**Why dual-write in Phase 1.** Keeps two readers (Obsidian, wiki-vault) functional during transition. Immutability of entries kills the main drift risk — entries land once, neither side updates content. Update tool only touches metadata, which lives only in Postgres.
|
||||
|
||||
**Why immutable entries.** Matches existing behavior — new phases get new files (`-phase2`, `-addendum`) rather than edits. Codifying this as a constraint removes a class of bugs and makes Phase N (Postgres-only) trivially achievable later.
|
||||
|
||||
**Why Postgres co-located with Trellis.** Trellis's plan explicitly chose schema-namespacing to leave room for consolidation. Same instance, separate schemas, no new infrastructure. Backup/recovery story is shared.
|
||||
|
||||
**Why not Trellis itself for project tracking.** Trellis is for conversation threads — coarse session-level checkpoints, append-only events, paused/resumed work. Projects are different: durable, named, status-bearing, visualized externally. Different lifecycle, different reader, different surface.
|
||||
|
||||
**Why the polymorphic tool shape.** Avoids tool sprawl. Adding a future artifact type (task, decision log, etc.) is a `kind` value, not a new MCP tool. Tradeoff is a fatter schema in the tool description.
|
||||
Loading…
Reference in New Issue
Block a user