AVPv1 — brain · skills · personas · spine

Not Zapier. Not IFTTT. This is situated cognitive guidance — clarifies what's invariant while the human decides. The system doesn't execute predetermined workflows; it enhances the human's capacity to work through their own process.

Academic grounding: Activity Theory. The invariant chains map to actions (stable across tools). Operations are fluid and technology-adoptable.

Source: mcp-and-skills-framework-and-brain-v3/research/invariant_driven.md

Single substrate on Hetzner (100.97.123.98), docker container postgres, accessible via Tailscale. pgvector + JSONB + stored procedures + full-text search + HNSW indexes.

Triple-index: pgvector + LanceDB + Tantivy. LanceDB non-negotiable for voice features.

Container

postgres (docker on cax31)

Access

ssh root@100.97.123.98 → docker exec postgres psql

Read-only role

claude_ro (views only, secrets blocked)

Write role

acebuddy (full, audited via audit_log)

• MCP for discovery — what can the system do? Browse via brain:// resources.
• Skills for procedure — how do you do it? Native Claude Code SKILL.md format.
• CLAUDE.md for declarative context — what does a new session need to know?

Skills + code + markdown in git (this repo + others). Dynamic state in Postgres on Hetzner, via Tailscale. Git is the distribution mechanism. Postgres is the runtime truth.

Never install Claude Code on Hetzner. Production surface, not dev surface. Admin only via SSH from dolphin or spud2.

1. Turn-footer commentary — writes one line on every turn, even "nothing to report." Silence kills the feature; the log is what makes check-in possible.
2. Check-in (on-demand query) — natural language: "Steve, status?" → pulls last ~20 rows from persona_comments WHERE persona_name='Steve'.
3. Specialist work (on-demand) — invoke by name; persona's bound skill fires; scans repos/brain/resources; writes a learnings row as byproduct. Steve only exists when invoked. NOT a background bot.
4. Broadcast participation — /broadcast fires all actives; each gets ~1000 tokens to report; collated into one chat block. Explicit tool, NEVER auto-fires.

Example footer:

---
🔧 Steve (APIs): no external calls this turn
📚 Librarian: turn 17 queued
👮 Cop: no drift

Session invariants HARD. Session Boss enforces. No drift. Examples: declared purpose, mode (sparring / execution / debug), budget cap.

Pipeline invariants SOFT. Outcome chains, not schedules. Each link checked at runtime; break → ntfy the pipeline's persona.

Groceries  =  need → captured → bought → dispatched → eaten
Research   =  question → queried → answered → extracted → stored
Email      =  arrived → triaged → digest → delivered → decided
Workbench  =  data → cleaned → analysed → reported → acted on

At session close, each persona_comments row gets a rating:

useful | noise | wrong

Three categories only. No KPI proliferation. No "persona quarterly reviews." Pierre's stated boundary — locked.

• Strangler fig at skill granularity — production-proven (VS Code, Obsidian, Neovim, Home Assistant).
• Use-case-first, not infrastructure-first. Reject the research's bootstrap order (read-file → query-db → register-skill). Start with domain skills.
• Lazy load ceiling: 5–8 active skills per session. Beyond that, measurable degradation.
• Delivery: MCP-first, not hook-first. One MCP tool semantic-search-skills(query, k) hits capability_view.

Two candidates. Pick one (or adopt both in layers).

Candidate A — native Claude Code (minimal)

---
name: skill-name
description: one-liner with triggering keywords
---

Full body as markdown — prose, examples, commands.

Candidate B — rich metadata (from research)

skill:
  id: "skill-name"
  version: "1.0.0"
  description: "what it does"
  keywords: ["tag1", "tag2"]
  category: "data-access|meta|domain|..."
  inputs: [{name, type, required}]
  outputs: [{name, type}]
  trust_level: "untested|trusted|verified|critical"
  cost_estimate: {tokens: 500, usd: 0.002}
  dependencies: ["postgres:brain", "mcp:vector-search"]
  last_tested: "2026-04-15"
  health: "healthy|degraded|broken"

1. Dry run — mocked deps, no side effects.
2. Integration test — real tools, controlled data.
3. Register — insert into Postgres skills with trust_level='verified'; update CLAUDE.md.
4. Health monitor — weekly test runs; degrade trust_level on failure.
5. Breaking-change detection — re-test all dependents when a dependency changes.

A user persona like Steve = one row in personas + one SKILL.md with his system prompt, scope, and tools.

• Persona name = the handle. /ask Steve, "Steve, status?", turn-footer 🔧 Steve (APIs): ...
• Skill = the capability. System prompt, tools, output shape.
• Collaboration = skill composition. "Steve + Dave, work on X" → both skills fire in parallel → outputs collate. No new infra.

Identified in monitor research (Apr 14, skill-framework-migration/output.md). The draft → extract → test → version → share loop has no tool yet. Not urgent. Future work.

-- Template for every v2 table
CREATE TABLE v2.example (
    id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
    status       TEXT NOT NULL DEFAULT 'active'
                 CHECK (status IN ('active','inactive','archived','superseded')),
    source       TEXT,
    metadata     JSONB NOT NULL DEFAULT '{}'
);

id

UUID primary key. Portable, merge-safe.

created_at

Immutable after INSERT.

updated_at

Maintained by v2.set_updated_at() trigger.

status

4 values. Replaces 4 inconsistent soft-delete patterns.

source

Provenance — 'manual', 'bot:weather', 'migration:v1', 'workbench:wb-...'

metadata

JSONB. Prevents new columns for edge cases.

Every table gets system-period temporal columns for full history.

ALTER TABLE v2.example ADD COLUMN
    valid_from TIMESTAMPTZ NOT NULL DEFAULT now(),
    valid_to   TIMESTAMPTZ NOT NULL DEFAULT 'infinity';

CREATE TABLE v2.example_history (LIKE v2.example INCLUDING ALL);

-- Trigger on UPDATE copies OLD to history with valid_to = now()

Time-travel query:

SELECT * FROM v2.entities
WHERE valid_from <= '2026-03-15' AND valid_to > '2026-03-15';

Every content-bearing table:

confidence  FLOAT,      -- Machine-generated, 0.0–1.0
importance  INTEGER,    -- Human-assigned, 1–5 (Pierre)

• confidence set by ingest pipelines. Transparent. Never a hidden filter.
• importance set by Pierre manually. Overrides machine scoring.
• Both VISIBLE in all search results. User sees 50 results, not 5.

These block the v3 framework. Follow universal standards (6 cols + temporal triggers where applicable).

CREATE TABLE v2.sessions (
    -- 6 universal columns
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    status          TEXT NOT NULL DEFAULT 'active'
                    CHECK (status IN ('active','ended','abandoned','archived')),
    source          TEXT,
    metadata        JSONB NOT NULL DEFAULT '{}',

    -- Session-specific
    project_path    TEXT,
    purpose         TEXT,                 -- declared by Session Boss
    mode            TEXT,                 -- 'sparring'|'execution'|'debug'
    started_at      TIMESTAMPTZ NOT NULL,
    ended_at        TIMESTAMPTZ,
    turn_count      INTEGER DEFAULT 0,
    tokens_total    INTEGER DEFAULT 0,
    budget_cap      INTEGER,

    -- Temporal
    valid_from      TIMESTAMPTZ NOT NULL DEFAULT now(),
    valid_to        TIMESTAMPTZ NOT NULL DEFAULT 'infinity'
);

CREATE TABLE v2.turns (
    -- 6 universal columns
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    status          TEXT NOT NULL DEFAULT 'ok'
                    CHECK (status IN ('ok','errored','archived')),
    source          TEXT,
    metadata        JSONB NOT NULL DEFAULT '{}',

    -- Turn-specific
    session_id      UUID NOT NULL REFERENCES v2.sessions(id),
    turn_num        INTEGER NOT NULL,
    started_at      TIMESTAMPTZ NOT NULL,
    ended_at        TIMESTAMPTZ,
    user_message    TEXT,
    assistant_response TEXT,
    tokens_in       INTEGER,
    tokens_out      INTEGER,
    tool_calls_count INTEGER DEFAULT 0,
    error_note      TEXT,

    -- Auditor fills async
    classified_at   TIMESTAMPTZ,
    classification  JSONB,

    UNIQUE(session_id, turn_num)
);

CREATE TABLE v2.personas (
    -- 6 universal columns
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    status          TEXT NOT NULL DEFAULT 'active'
                    CHECK (status IN ('active','inactive','archived')),
    source          TEXT,
    metadata        JSONB NOT NULL DEFAULT '{}',

    -- Persona-specific
    name            TEXT NOT NULL UNIQUE,
    emoji           TEXT NOT NULL,
    job             TEXT NOT NULL,
    scope           TEXT,
    tier            TEXT NOT NULL CHECK (tier IN ('system','user')),
    skill_binding   TEXT,
    created_by_session UUID REFERENCES v2.sessions(id)
);

CREATE TABLE v2.persona_comments (
    -- 6 universal columns
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    status          TEXT NOT NULL DEFAULT 'active',
    source          TEXT,
    metadata        JSONB NOT NULL DEFAULT '{}',

    -- Comment-specific
    persona_id      UUID NOT NULL REFERENCES v2.personas(id),
    session_id      UUID NOT NULL REFERENCES v2.sessions(id),
    turn_id         UUID REFERENCES v2.turns(id),
    turn_num        INTEGER,
    comment         TEXT NOT NULL,

    -- Auditor fills at session close
    rating          TEXT CHECK (rating IN ('useful','noise','wrong',NULL)),
    rated_at        TIMESTAMPTZ,

    UNIQUE(persona_id, session_id, turn_num)
);

CREATE TABLE v2.drift_events (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    status          TEXT NOT NULL DEFAULT 'active',
    source          TEXT,
    metadata        JSONB NOT NULL DEFAULT '{}',

    session_id      UUID REFERENCES v2.sessions(id),
    turn_id         UUID REFERENCES v2.turns(id),
    drift_type      TEXT NOT NULL CHECK (drift_type IN ('ai','user')),
    detail          TEXT,
    triggered_checkpoint BOOLEAN DEFAULT false
);

• Event-sourced ingest pattern — decision #14 flagged "RESEARCH NEEDED before committing."
• status column on v1 learnings — required to triage 973 unreviewed rows. Blocked on migration.
• github_repos sync — currently 8 rows, actual ≈60. Fix before atlas Phase 1.
• claude_sessions sync — broke 2026-04-05. Fix.

Three files. Nothing else. Schema contract is the hard-to-change surface; bash hooks are trivial.

mcp-and-skills-framework-and-brain-v3/
  migrations/
    001_spine.sql          -- v2.sessions + v2.turns (6 universal cols + triggers)
~/.claude/hooks/
  session-start.sh         -- INSERT session row via SSH + docker exec, exit
  stop.sh                  -- INSERT turn row via SSH + docker exec, exit

Then register both in ~/.claude/settings.json.

5. Tailscale pre-flight — hook verifies tunnel before brain ops. Lives inside session-start.sh as bail condition.
6. Budget tracker — derived: SELECT SUM(tokens_in+tokens_out) FROM v2.turns WHERE session_id=$1. No state needed.
7. Handoff auto-append — soft contract. session-start.sh opens HANDOFF.md for append; stop.sh writes turn summary.
8. Write-failure flagging + retry queue — metadata flag on turns row; periodic retry skill.

9. Persona declarations, /persona create skill, footer enforcement
10. Statusline control board (budget, turn count, active personas, brain write status, time)
11. Auditor /done skill (batch classification, ratings, mistake detection)
12. Cop drift detector (background per turn, checkpoint at 3 events)
13. Archivist commit + push + /undo
14. Time hook (wall clock + prediction-vs-actual calibration)

session-start.sh

#!/bin/bash
# v3 Tier A: SessionStart hook — writes v2.sessions row

SESSION_ID=$(cat /proc/sys/kernel/random/uuid)
PROJECT_PATH="$CLAUDE_PROJECT_DIR"
STARTED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

ssh root@100.97.123.98 "docker exec postgres psql -U acebuddy -d brain -c \"
INSERT INTO v2.sessions (id, project_path, started_at, source, mode)
VALUES ('$SESSION_ID', '$PROJECT_PATH', '$STARTED_AT', 'claude-code', 'sparring');
\"" || {
  echo '{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":\"⚠️ BRAIN WRITE FAILED — session not logged\"}}'
  exit 2
}

echo "$SESSION_ID" > /tmp/claude-session-id
exit 0

stop.sh

#!/bin/bash
# v3 Tier A: Stop hook — writes v2.turns row after every turn

SESSION_ID=$(cat /tmp/claude-session-id 2>/dev/null)
[ -z "$SESSION_ID" ] && exit 0   # no session? no turn.

TURN_NUM=$(ssh root@100.97.123.98 "docker exec postgres psql -U acebuddy -d brain -tAc \"
SELECT COALESCE(MAX(turn_num),0)+1 FROM v2.turns WHERE session_id='$SESSION_ID';
\"")

# (read turn data from $CLAUDE_TRANSCRIPT_PATH, extract tokens/tool calls)
# (INSERT v2.turns row)

exit 0

Actual implementation: escape properly, fail loud on DB error, extract tokens from transcript.

• [ ] Pierre confirms Tier A framing (implicit yes on Apr 14; re-confirm)
• [ ] Confirm migrations at mcp-and-skills-framework-and-brain-v3/migrations/
• [ ] Confirm hooks at ~/.claude/hooks/ (user scope, cross-project)
• [ ] Confirm connection: SSH + docker exec postgres psql -U acebuddy -d brain
• [ ] Decide session_id format (Q13)
• [ ] Decide whether to include personas + persona_comments in 001_spine.sql (include-as-empty) or separate 002_personas.sql later
• [ ] Decide whether spine runs in v2 schema or separate spine schema (leaning: v2 — one cutover path)

• atlas/MIGRATION.md — schema v2 spec (canonical base)
• atlas/PROPOSAL.md — skill layer + spine architecture (outdated on delivery mechanism; extension approach still correct)
• atlas/HANDOFF.md — atlas session 3 (MCP-first correction)
• atlas/research/validation/VALIDATION.md — proposal critique
• atlas/research/orchestration/answer.md — multi-session orchestration research
• mcp-and-skills-framework-and-brain-v3/.planning/HANDOFF.md — Apr 13 architecture sparring
• monitor/HANDOFF-session-2.md — Apr 14 personas + four-block sparring
• monitor/sparring-deploy/spoken-script.txt — 7-min MP3 narration source
• Session 2861cad1-5ab5-4a0d-86c0-8ac9172756c0.jsonl lines 33–83 — Steve/personas deep sparring (Apr 14 evening)

• monitor/results/skill-framework-migration/output.md — strangler fig validation, skill-builder gap
• monitor/results/brain-db-skill-integration/output.md — MCP + read-only views, three-tier write pattern
• mcp-and-skills-framework-and-brain-v3/research/invariant_driven.md — Activity Theory grounding, five-layer arch
• mcp-and-skills-framework-and-brain-v3/research/hive_mind.md — distributed cognition, LISTEN/NOTIFY, offline-first
• mcp-and-skills-framework-and-brain-v3/research/skills_first.md — skill metadata, lock-it-in gate

At ~/.claude/projects/C--Users-acebu-projects/memory/:

• user_persona_cognitive_style.md — the non-negotiable cognitive rule
• feedback_satisficing_redundancy.md — why three repos are not to be consolidated
• project_v3_framework_state.md — sparring state snapshot (points here)
• reference_v3_canonical_handoff.md — where this doc lives
• reference_atlas_brain_v2.md — atlas hub pointer
• reference_ingest_api.md — brain DB ingest endpoint

• monitor-sparring.pages.dev — sparring notes + 7-min MP3 narration
• Direct MP3 (2.8 MB, Edge TTS Ryan voice)
• brain-db dashboard — 122-table data dictionary (auth-gated)
• brain-audit dashboard — 5-dimension audit
• GitHub repo (private)