# Zion PM v2 - Build Spec (SEED)

> **Status:** AUTHORITATIVE build charter. Execute top-to-bottom.

> **Origin:** Authored by GLM (CT247 opencode session) for Claude CT215 to implement.

> **Date:** 2026-06-20. **Target:** live today.

> **Replaces:** `claude-memory/zion-pm-conductor.md` (the earlier sketch - this is the real build).

---

## 1. Mission

A single self-hosted app that is Zion's **Project Manager**. The PM is GLM (Z.ai) - it takes any task,

decomposes it, **delegates work to the other models** (Claude Max, Codex Max, local Ollama),

supervises, and gates every outward action behind an approval outbox. The UX is one unified surface:

**Chat channels** (pick a model when creating a channel, or `@model` mid-chat), a **Board** (tasks), and a

**Fleet** pane (worker status + quota gauges). It absorbs the channel/mention concepts of Mattermost and

the board concept of Plane.so **into one bespoke Mastra app** - no dependency on either.

The PM system is built by the model fleet it will eventually manage - Claude CT215 is the lead executor

of this spec.

## 2. Locked decisions (do NOT re-litigate)

| Decision | Value | Rationale |

|---|---|---|

| Brain runtime | **Mastra (TypeScript)** | User choice; agent/workflow primitives + Next.js pairing |

| Host | **CT120** (destroy + recreate clean Debian 12) | Was parked `perseus` 1c/1GB; repurposed |

| Surface | **Unified bespoke app** (no Mattermost/Plane fork) | "Fork into one" = one Mastra app absorbing their concepts |

| PM brain model | **GLM** via Z.ai Coding Plan **subscription** (weekly cap, NOT PAYG) - Anthropic-compat endpoint | Frees Claude Max for dev work; model id via `PM_BRAIN_MODEL` env (default = what the plan serves, e.g. `glm-4.6`/`glm-5.2`; confirm at build) |

| Model roster | GLM (Z.ai Coding Plan sub), Claude Max, Codex Max, local Ollama | **No PAYG per-token API ever.** Subscription-only: CLI/container-auth (Claude, Codex) + Z.ai Coding Plan sub. Adding a future subscription model = 1 adapter file (see §6) |

| Delegation primitive | **Spawn agent processes** (CLI/SSH/HTTP), not API calls | Auth lives inside each logged-in worker |

| Build horizon | **Today** | Parallel dispatch across the fleet |

## 3. Verified infra facts (build on these)

### CT120 - target host

- **Current:** `perseus`, PARKED 2026-06-16, stopped, onboot=0, 1c/1024MB, rootfs intact.

- **Action:** `pct destroy 120` then recreate clean from debian-12 template (see §9 step 1).

- **Recommended resources:** **4 cores / 6GB RAM / 2GB swap / 24GB disk, onboot=1.**

- **Recommended IP:** static **REDACTED-IP** (mnemonic, free).

- **Host:** pve node `root@REDACTED-IP` (Dell R410, Xeon E5645, 24c/31GB, 3.5TB free).

### Fleet endpoints (all LAN-reachable from CT120)

| Role | Host | Transport | Notes |

|---|---|---|---|

| GLM brain (this PM) | `https://api.z.ai/api/anthropic` | HTTPS, `ZAI_API_KEY` (from Z.ai Coding Plan **subscription**, weekly cap - NOT PAYG) | Anthropic-compat; model id via `PM_BRAIN_MODEL` env, default = plan's current (this CT247 session routes `zai/glm-5.2`; confirm `/api/anthropic` id at build) |

| Claude Max worker | `zion@REDACTED-IP` (CT215) | SSH + `claude -p` | Claude Code, `--dangerously-skip-permissions` ok; tmux pool optional |

| Codex Max worker | `zion@REDACTED-IP` (CT241) | SSH + `codex exec` | `codex-full`/`cdx` wrappers; `approval_policy=never`, full sandbox |

| Ollama worker (free tier) | `http://REDACTED-IP:11434` (CT205) | HTTP `/api/chat` | RTX 3060 12GB on pve-gpu node; models: `qwen2.5-coder:7b`, `deepseek-coder-v2`, `mistral-nemo:12b` |

| Ollama overflow | `http://REDACTED-IP:11434` (WIN3060) | HTTP | Second 3060; desktop may sleep - optional |

| homelab-rag MCP | `http://REDACTED-IP:9876/sse` | SSE | Conductor's `queryMemory` tool |

| cbm-homelab MCP | `http://REDACTED-IP:9877/sse` | SSE | Conductor's `queryGraph` tool |

| serena MCP | `http://REDACTED-IP:9878/sse` | SSE | Optional for MVP |

| memory-graph MCP | `http://REDACTED-IP:9879/sse` | SSE | Optional for MVP; durable cross-agent memory |

| Traefik edge | CT244 `REDACTED-IP` | dynamic YAML | `/opt/edge/traefik/dynamic/*.yml` |

| Authentik SSO | CT246 `REDACTED-HOST` | forwardAuth middleware | Reuse `authentik-forwardauth@docker` (same as vault.lab/notes.lab) |

### Operational doctrine (from homelab conventions - obey)

- **noexec CIFS rule:** the canonical repo lives at `/shared/projects/zion-pm/` (git, committed from CT215),

  but the **app runs from CT120 local fs** `/opt/zion-pm`. Deploy = `git clone` / `git pull` on CT120. Never

  execute from the share.

- **RAG-first:** the conductor must call `queryMemory` (homelab-rag MCP) before reading/grepping files.

- **Secret hygiene:** `ZAI_API_KEY` lives in `/shared/projects/.env.secrets` (has CRLF - strip when sourcing).

  Workers SSH via **keys**, never passwords in code. Treat `[REDACTED:...]` as proof a secret exists.

- **Approval outbox:** every outward action (email / deploy / publish / infra) **drafts** - never auto-fires.

  Internal/reversible work (PM↔worker delegation, file edits) is full-auto.

- **Git:** commits to `/shared/projects` happen from CT215 (per homelab rule).

## 4. Architecture

```

                 ┌─────────────── REDACTED-HOST (Traefik+Authentik) ──────────────┐

   Zion (PWA) ──▶│            Next.js UI - Chat / Board / Fleet panes (:4100)            │

                 └─────────────────────────────┬──────────────────────────────────────────┘

                                               │ websocket / REST

                                               ▼

                                  ┌─────────── Mastra runtime ────────────┐

                                  │  pmConductor agent (GLM via Z.ai)      │

                                  │  Tools:                                │

                                  │   delegate(model, task, opts)          │

                                  │   createTask / updateTask              │

                                  │   draftApproval(action)                │

                                  │   queryMemory (→ homelab-rag MCP)      │

                                  │   queryGraph  (→ cbm-homelab MCP)      │

                                  └───┬──────────┬──────────┬──────────┬───┘

                                      ▼          ▼          ▼          ▼

                   ┌─────────────────────────────────────────────────────────┐

                   │  Worker adapters (TS)        cap table (sqlite)         │

                   │   claude   → SSH CT215  `claude -p`        ▓▓▓░ Max     │

                   │   codex    → SSH CT241  `codex exec`       ▓▓░░ Max     │

                    │   ollama   → HTTP CT205 /api/chat          ▓▓▓▓ free     │

                    └─────────────────────────────────────────────────────────┘

              (GLM conductor is the brain itself - NOT a worker adapter. Workers = claude/codex/ollama only.)

                                      │

                                      ▼  (every worker may also mount the 4 MCPs)

                              shared memory substrate (rag + cbm + serena + mem-graph)

```

### Layers

1. **Mastra runtime** - `pmConductor` agent (GLM). Holds the system prompt, the tool registry, and the

   workflow for decompose→delegate→verify.

2. **Worker adapters** - one TS module per model behind a unified `delegate()` entry point. Each knows its

   transport. A **cap table** gates availability and provides tier fallback.

3. **Router** - message ingestion → resolve channel-default-model + parse `@mentions` → route to conductor

   (if glm) or direct-dispatch (otherwise) → stream reply back to UI.

4. **Web UI (Next.js)** - three panes: Chat, Board, Fleet. Mobile-first PWA.

5. **Store** - libSQL/sqlite at `/opt/zion-pm/data/zionpm.db`.

6. **Edge** - Traefik `pm.lab` route + Authentik forwardAuth.

## 5. Data model (sqlite)

```sql

CREATE TABLE channels(

  id            TEXT PRIMARY KEY,           -- ulid

  name          TEXT NOT NULL UNIQUE,

  default_model TEXT NOT NULL,              -- glm|claude|codex|ollama

  created_at    INTEGER NOT NULL

);

CREATE TABLE messages(

  id            TEXT PRIMARY KEY,

  channel_id    TEXT NOT NULL REFERENCES channels(id),

  role          TEXT NOT NULL,              -- user|assistant|system

  author_model  TEXT,                       -- which model produced an assistant msg

  body          TEXT NOT NULL,

  parent_id     TEXT REFERENCES messages(id), -- threading

  created_at    INTEGER NOT NULL

);

CREATE TABLE tasks(

  id            TEXT PRIMARY KEY,

  title         TEXT NOT NULL,

  status        TEXT NOT NULL DEFAULT 'todo', -- todo|doing|done|blocked

  assigned_model TEXT,

  channel_id    TEXT REFERENCES channels(id),

  created_at    INTEGER NOT NULL,

  updated_at    INTEGER NOT NULL

);

CREATE TABLE outbox(                          -- approval-gated outward actions

  id           TEXT PRIMARY KEY,

  action_type  TEXT NOT NULL,                 -- email|deploy|publish|infra

  payload_json TEXT NOT NULL,

  status       TEXT NOT NULL DEFAULT 'draft', -- draft|approved|rejected|sent

  created_at   INTEGER NOT NULL,

  approved_at  INTEGER

);

CREATE TABLE cap_state(

  model        TEXT PRIMARY KEY,

  available    INTEGER NOT NULL,              -- 0/1

  reason       TEXT,

  last_checked INTEGER NOT NULL

);

```

## 6. Worker adapter contracts (the delegation core)

### Types

```ts

export type ModelId = 'glm' | 'claude' | 'codex' | 'ollama';

export type OllamaModel = 'qwen2.5-coder:7b' | 'deepseek-coder-v2:16b' | 'mistral-nemo:12b';

export interface DelegateParams {

  model: ModelId;

  ollamaModel?: OllamaModel;   // required iff model === 'ollama'

  task: string;                // the work envelope (self-contained)

  context?: string;            // RAG/graph snippets to inject

  cwd?: string;                // working dir on the worker host (claude/codex)

  timeoutMs?: number;          // default 120_000

}

export interface DelegateResult {

  ok: boolean;

  output: string;              // stdout / model reply

  artifacts: string[];         // file paths produced (claude/codex)

  error?: string;

  durationMs: number;

}

```

### `delegate()` entry point (src/workers/delegate.ts)

1. Check `cap_state[model]`; if unavailable, **escalate tier**: claude→codex→ollama (strong→weak).

   The conductor may override.

2. Call the matching adapter.

3. Persist a `messages` row (author_model) + update `cap_state.last_checked`.

4. Return `DelegateResult`.

### Adapters

- **`claudeAdapter`** (src/workers/claude.ts): SSH `zion@REDACTED-IP`, run

  `claude -p '<task>' --dangerously-skip-permissions` in `cwd` (default `/shared/projects`). Capture stdout.

  Use `ssh2` (node) with key auth. MVP = one-shot; phase 2 = tmux pool `pm-claude-N`.

- **`codexAdapter`** (src/workers/codex.ts): SSH `zion@REDACTED-IP`, run `codex exec '<task>'`

  (or `cdx` wrapper) in `cwd`. Capture stdout.

- **`ollamaAdapter`** (src/workers/ollama.ts): `POST http://REDACTED-IP:11434/api/chat`

  `{model: ollamaModel, messages:[{role:'system',...},{role:'user',content:task}], stream:false}`.

  Parse `message.content`.

> **No `glm-sub` adapter** - the conductor (GLM) does all GLM reasoning itself. Worker tier = claude/codex/ollama only.

>

> **Adding a future subscription model** (e.g. a Gemini CLI sub, Cursor, etc.): create one new

> `src/workers/<model>.ts` implementing the `DelegateParams→DelegateResult` contract, add one row to

> `cap_state`, and one option in the channel model-picker + mention grammar. Same pattern as claude/codex.

### SSH key setup (WS-A, once)

On CT120 as the app user: `ssh-keygen -t ed25519 -N "" -f ~/.ssh/id_ed25519`, then append the pubkey to

`/home/zion/.ssh/authorized_keys` on **CT215** and **CT241** (the user `zion`). Verify:

`ssh -o BatchMode=yes zion@REDACTED-IP 'echo ok'` returns `ok`.

## 7. Router (channel-default + @mention)

```ts

// src/router.ts - pseudocode

async function onMessage(channelId, userId, text) {

  const binding  = (await db.channels.get(channelId)).default_model;

  const mentions = parseMentions(text);                 // ['@claude', ...] → ['claude']

  const targets  = mentions.length ? mentions : [binding];

  const ragCtx = await conductor.tools.queryMemory(text); // always inject memory

  for (const target of targets) {

    let reply: string;

    if (target === 'glm') {

      // conductor owns it: may decompose + sub-delegate + verify

      reply = (await conductor.run(text, { channelId, context: ragCtx })).text;

    } else {

      reply = (await delegate({ model: target, task: text, context: ragCtx })).output;

    }

    await db.messages.insert({ channelId, role:'assistant', author_model: target,

                               body: reply, parentId, createdAt: Date.now() });

    io.to(channelId).emit('message', { ... });           // push to UI

  }

}

```

**Mention grammar:** `@(glm|claude|codex|ollama)(?::(\S+))?` - the optional `:model` suffix selects an

Ollama model, e.g. `@ollama:mistral-nemo:12b`. Mention wins over channel-default **for that turn only**.

## 8. Web UI (Next.js, three panes)

- **Chat** - left: channel list (each shows its default-model badge). Main: threaded message view with

  author-model color coding + @mention chips. Composer shows the active target model. **New Channel modal:

  name + model `<select>`** (the "select model in a new channel" UX).

- **Board** - kanban (todo / doing / done / blocked). Cards = tasks. Drag = status change. Click card →

  assign model, link to channel.

- **Fleet** - table: model | status | last task | cap gauge | `Ping` button (runs a trivial delegate and

  reports latency). Live-updates via websocket.

Stack: Next.js App Router, Tailwind, `@mastra/core`, socket.io (or server actions + polling for MVP).

Auth = Authentik header (`X-Forwarded-User`) trusted behind Traefik; map to a local user row.

## 9. Build steps (dependency order)

### WS-A - CT120 provision (operator, gates everything)

```bash

# on pve node root@REDACTED-IP

pct stop 120 2>/dev/null; pct destroy 120 --purge

# create clean debian-12 CT (adjust template/storage to what pve has)

pct create debian-12 120 \

  --hostname zion-pm --cores 4 --memory 6144 --swap 2048 \

  --rootfs local-lvm:24 --onboot 1 \

  --net0 name=eth0,bridge=vmbr0,ip=REDACTED-IP/24,gw=REDACTED-IP

pct start 120

pct enter 120

# inside CT120:

apt update && apt -y install nodejs npm git build-essential curl python3

curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && apt -y install nodejs   # Node 20 LTS

npm i -g pnpm

# SSH keys for the app user (run as root or a dedicated 'zionpm' user):

ssh-keygen -t ed25519 -N "" -f /root/.ssh/id_ed25519

# distribute pubkey to CT215 + CT241 ~/.ssh/authorized_keys (zion user)

ssh -o BatchMode=yes zion@REDACTED-IP 'echo ok'   # must print ok

```

### WS-B - Mastra scaffold + conductor (Codex CT241 or Claude CT215)

```bash

# on CT120, in /opt

cd /opt && pnpm create mastra@latest zion-pm --template nextjs

cd zion-pm && pnpm install

pnpm add @mastra/mcp ssh2 better-sqlite3 ulid socket.io

```

- Wire GLM via Z.ai Anthropic-compat (set `ZAI_API_KEY` env, base URL `https://api.z.ai/api/anthropic`).

- Define `pmConductor` agent (`src/mastra/agents/pm.ts`) with the §4 tool registry.

- Register MCP clients for homelab-rag + cbm-homelab via `@mastra/mcp` (SSE URLs in §3).

### WS-C - Worker adapters + cap table (Claude CT215)

Implement §6 exactly: `src/workers/{delegate,claude,codex,ollama}.ts` (3 adapters + delegate entry) + `src/db.ts`

(better-sqlite3, schema in §5). Seed `cap_state` with `claude`,`codex`,`ollama` all `available=1` (glm = conductor, not a worker row).

### WS-D - Next.js UI (Claude CT215)

Implement §8: Chat / Board / Fleet panes, new-channel model picker, @mention rendering. Seed channels:

`#pm`(glm), `#claude`, `#codex`, `#ollama`.

### WS-E - Router (GLM CT247 / this session can also do it)

Implement §7: message ingestion, channel-default + mention parse, dispatch loop, websocket push.

### WS-F - Edge + SSO (Codex CT241)

On CT244 add `/opt/edge/traefik/dynamic/pm.yml`:

```yaml

http:

  routers:

    pm:

      rule: Host(`REDACTED-HOST`)

      entrypoints: [websecure]

      tls: { certResolver: letsencrypt }

      service: pm

      middlewares: [authentik-forwardauth@docker]

  services:

    pm:

      loadBalancer:

        servers: [{ url: http://REDACTED-IP:4100 }]

```

Add `REDACTED-HOST` to AdGuard/local DNS → CT244. Reload Traefik. Confirm Authentik forwardAuth

applies (mirror `vault.lab`).

### WS-G - Integration + e2e test (GLM, this session)

Run the §10 acceptance test. Document at `/shared/projects/zion-pm/` (README, ops runbook, this SEED).

Git-commit from CT215.

## 10. Acceptance test - "done today" bar

All of these must pass end-to-end on `https://REDACTED-HOST`:

1. **Boot:** CT120 clean, app serves :4100, `pm.lab` resolves behind Authentik login.

2. **Channels seeded:** `#pm`(glm), `#claude`, `#codex`, `#ollama` visible with correct model badges.

3. **GLM conductor (channel-default):** Post in `#pm`: *"Summarize the cbm-homelab project's architecture

   in 5 bullets."* → conductor calls `queryMemory`/`queryGraph` → posts a 5-bullet reply authored by `glm`.

4. **@mention override:** In `#pm`: *"@ollama:mistral-nemo:12b suggest 3 names for this PM app"* → routes

   to Ollama CT205 → inline reply authored by `ollama`, despite channel default being glm.

5. **Heavy delegation:** In `#pm`: *"@claude create a README.md at /shared/projects/zion-pm/ describing this

   app"* → claude adapter SSHes CT215, runs `claude -p`, returns → reply posts with the file path; file exists.

6. **Board:** a task created from a conversation appears on the Board, assignable, drag todo→done persists.

7. **Fleet:** all three workers (claude/codex/ollama) + the GLM conductor show green; `Ping` returns latency for each.

8. **Approval outbox:** conductor drafts a (stub) outward action → appears as `draft` in outbox → UI shows

   Approve/Reject → approving marks `approved`; nothing auto-sends.

## 11. Operating rules (non-negotiable)

1. **noexec CIFS** - app runs from `/opt/zion-pm` on CT120, never from `/shared/projects`.

2. **RAG-first** - conductor queries homelab-rag MCP before any file read.

3. **Secrets** - `ZAI_API_KEY` from `.env.secrets` (strip CRLF); SSH keys only; never print secrets.

4. **Approval outbox** - outward actions draft only; internal delegation is full-auto.

5. **Git** - canonical repo at `/shared/projects/zion-pm`, remote = **private `github.com/zionboggan/zion-pm`**; commit + push from CT215; CT120 deploys via `git pull`.

6. **Cap-aware** - never silently drop a task; fall through tiers or queue with a visible Board card.

## 12. Out of scope (phase 2+)

- Voice/email intake (`intake-voice.sh`, `intake-email.py` from the old sketch).

- Multi-account email sender identities (`policy.yaml > sender_identities`).

- Cockpit PWA skin over this app's API.

- Tmux worker pools (MVP is ephemeral one-shot `claude -p`/`codex exec`; promote to persistent pooled sessions later).

- Cap auto-detection from Claude/Codex/Z.ai usage endpoints.

- serena + memory-graph MCP wired into workers (MVP uses rag + cbm only).

---

**Handoff line for Claude CT215:**

> Read `/root/zion-pm/SEED.md` on CT247 (`ssh root@REDACTED-IP 'cat /root/zion-pm/SEED.md'`),

> copy it to `/shared/projects/zion-pm/SEED.md`, then execute WS-A through WS-G per §9. Lead = you

> (Claude CT215). Delegate WS-B/F to Codex CT241, WS-E/G stays with GLM. Target: §10 acceptance today.

> Obey §11. (Decisions baked in: 3 adapters - glm-sub dropped; GLM brain = Z.ai Coding Plan sub not PAYG;

> repo = private github.com/zionboggan/zion-pm; workers = ephemeral one-shot.)

> **Note on file location:** CT247's local `/shared/projects` mount is read-only (`nobody:nogroup`) and

> CT247→CT215 SSH is not peered, so the spec could not be written directly to the canonical share from CT247.

> Claude CT215 fetches it via the SSH command above (CT215→CT247 needs to be peered, or Zion copy-pastes

> the content). After fetch, commit it to `/shared/projects/zion-pm/SEED.md` as the first WS-G step.