Skip to main content

GOTCHA Framework & System Handbook

John — System Handbook (On-Demand Reference)

Load this when you need infrastructure details, CLI commands, or system layout. Your identity, routing, and rules are in ~/.claude/CLAUDE.md and ~/system/rules/john-operating-system.md.

For orchestration surface routing (DAG vs chains vs factory vs one-shot), see ~/system/rules/orchestration-surface.md.

GOTCHA Framework

GOT (Engine): Goals (specs/, rules/) | Orchestration (you) | Tools (tools/) CHA (Context): Context (context/) | Hard prompts (prompts/) | Args (config/)

AI errors compound (90%^5 = 59%). So: reliability -> deterministic code, flexibility -> LLM, process -> goals, knowledge -> context/memory.

System Layout

~/system/
  tools/          <- 1,310 scripts (manifest-index.md for lookup)
  rules/          <- Standards + john-operating-system.md
  specs/          <- Plans and specifications
  context/        <- Reference material
  prompts/        <- Instruction templates
  config/         <- Configuration
  databases/      <- SQLite (mission-control.db, costs.db, hivemind.db, etc.)
  agents/         <- identities/ + state/ + hivemind/ + specialist-mapping.json
  kernel/         <- agent-scheduler.js
  reports/        <- Generated reports

~/.claude/
  CLAUDE.md       <- Identity + routing + constraints (ALWAYS loaded)
  hooks/          <- Kotlin security enforcement
  agents/         <- builder.md + validator.md
  skills/         <- 80+ skills

Task Management — Mission Control

node ~/system/tools/mc.js list                    # All open tasks
node ~/system/tools/mc.js list --owner john       # My tasks
node ~/system/tools/mc.js add "Title" --desc "X" --priority H --owner john
node ~/system/tools/mc.js start <id>              # Start
node ~/system/tools/mc.js done <id> "outcome"     # Complete (quality gate)
node ~/system/tools/mc.js ready <id>              # Mark ready for review
node ~/system/tools/mc.js pause <id>              # Pause
node ~/system/tools/mc.js show <id>               # Full details
node ~/system/tools/mc.js active                  # Who's working on what
node ~/system/tools/mc.js stats                   # Summary counts

# Collision prevention (cross-session claim protocol)
node ~/system/tools/mc.js claim <id> --actor <name> --session <id>  # Acquire lease
node ~/system/tools/mc.js claim-release <id>                         # Release lease
node ~/system/tools/mc.js claim-status <id>                          # Check lease status
# See: https://docs.alai.no/books/infrastructure/page/mc-claim-protocol

Communication — Slack Only

node ~/system/tools/slack.js send <channel> "message"
node ~/system/tools/slack.js read <channel> [limit]

Workspace: alai-talk.slack.com

BookStack Wiki

URL: https://docs.alai.no Sync: node ~/system/tools/bookstack-sync.js sync Daemon: com.john.bookstack-sync (auto-sync every 5 min)

Infrastructure

Cloud (Azure VM — Production Supporting)

Service URL
BookStack https://docs.alai.no
Vaultwarden https://vault.alai.no
Documenso https://sign.alai.no
Grafana https://grafana.alai.no
Planka https://boards.alai.no

VM: 4.223.110.181 | swedencentral | SSH: ssh -i ~/.ssh/azure_alai [email protected]

Local (ANVIL — Dev Only)

Service Port
Postgres/Redis per product 5432-5437
Qdrant (vector search) 6333
Ollama ANVIL 11434
FORGE LLM (MLX) 10.0.0.2:11435 (local Thunderbolt) / 100.94.54.37:11435 (Tailscale, host alem-sin-mac-studio) — MLX OpenAI /v1, PRIMARY. Ollama :11434 on FORGE currently DOWN. Old Tailscale 100.104.164.86 (basicass-mac-mini) offline since ~2026-06-14.
MC Dashboard localhost:3030

Cost Tracking

node ~/system/tools/cost-tracker.js summary today|week|month
node ~/system/tools/mc.js run start <task_id> <agent>    # Track run
node ~/system/tools/agent-manager.js budget-check <id>   # Check before delegating

SQLite Databases — ~/system/databases/

Key: mission-control.db, costs.db, hivemind.db, knowledge.db (187MB), events.db

Security

Forbidden (NEVER):

  • Browser profiles, ~/Documents, ~/Desktop, ~/Downloads
  • SSH keys, Keychains, Mail, Messages, Photos
  • Deploy/email/delete/finance without asking

Backup Protocol

bash ~/system/tools/setup-backup.sh "description"

No comments to display

Back to top