Begin/End skills: a revision-labeled cold start for AI agents

# ─────────────────────────────────────────────────────────────
# begin — a revision-labeled cold start. Run before an agent acts.
# ─────────────────────────────────────────────────────────────
cat > ~/.local/bin/kb-begin <<'EOF'
#!/bin/bash
set -euo pipefail
VAULT="$HOME/wiki"

# 1. Record the canonical commit. Label all context with it.
COMMIT=$(git -C "$VAULT" rev-parse HEAD)
echo "canonical commit: $COMMIT"

# 2. Note working-tree state (unexplained changes are a red flag)
DIRTY=$(git -C "$VAULT" status --porcelain | grep -v '.obsidian\|.trash' || true)
[ -n "$DIRTY" ] && echo "WARNING: unexplained working-tree changes:" && echo "$DIRTY"

# 3. FAIL CLOSED: if a derived index reports a different commit, stop.
if [ -f "$VAULT/.index-commit" ]; then
  IDX=$(cat "$VAULT/.index-commit")
  if [ "$IDX" != "$COMMIT" ]; then
    echo "FAIL CLOSED: index at $IDX != vault HEAD $COMMIT (stale). Stopping."
    exit 3
  fi
fi

# 4. Print the stable entry points for the agent to read (smallest set)
echo "--- start context (read these, labeled @ $COMMIT) ---"
cat "$VAULT/agents/context-manifest.md" 2>/dev/null || echo "(no manifest)"
EOF
chmod +x ~/.local/bin/kb-begin

# ─────────────────────────────────────────────────────────────
# end — persist a durable outcome through the controlled writer.
# Never a raw git commit on the authority.
# ─────────────────────────────────────────────────────────────
cat > ~/.local/bin/kb-end <<'EOF'
#!/bin/bash
set -euo pipefail
# $1 = a /tmp write script produced by the agent (enumerated files,
#      stdin-fed audit, enumerated git add, commit, refresh, verify)
WRITE_SCRIPT="${1:?usage: kb-end <write-script.sh>}"
canonical-writer-lock.py -- bash "$WRITE_SCRIPT"

# Verify the commit actually landed before claiming success.
git -C "$HOME/wiki" rev-parse HEAD
echo "end: outcome persisted. If the commit above is unchanged, the write FAILED."
EOF
chmod +x ~/.local/bin/kb-end

# ─────────────────────────────────────────────────────────────
# Thin adapter: wire begin/end into whatever agent harness you use.
# Example — a Claude Code slash-command / skill wrapper.
# ─────────────────────────────────────────────────────────────
# In your agent's startup hook or skill:
#   kb-begin            # runs the cold start, prints commit + context
#   ... agent does the task ...
#   kb-end /tmp/agent-write.sh   # persists via the writer lock

What this does

Provides two small skills that bracket an AI agent’s work against a Git vault. begin records the canonical commit, flags unexplained working-tree changes, fails closed if a derived index reports a different commit, and prints the smallest start context the task needs. end persists a durable outcome only through the controlled-writer lock and confirms the commit landed. A thin adapter wires both into whatever agent harness you run, so every agent cold-starts and persists identically.

Why this approach

An AI agent is, at its core, a language model that operates on whatever context it’s given at the start of a session. Without a structured beginning, that context is whatever the model was last told, whatever it inferred from training data, or whatever a cached prompt happens to contain. For a homelab assistant, that means an agent might confidently tell you that a container is running when it was stopped an hour ago, or suggest a command that relied on a service you’ve since moved.

The begin skill solves this by making the agent’s first act a verified read of the canonical vault state. It reads the current Git commit, loads a compact overview of the vault (a generated digest covering all regions, guardrails, and a resume pointer), does a quick delta check to identify what changed since the last session, and only then loads the specific topic pages the task requires. The result is an agent that starts with proven-current knowledge of your actual setup rather than a stale model of what your setup used to look like.

The end skill is the write-path counterpart. Without it, an agent that discovers something important has two options: put it in a prompt summary that evaporates at session end, or do a raw git commit directly to the vault. Both are bad. The summary evaporates; the raw commit bypasses every validation gate — broken links, committed secrets, missing frontmatter — that the controlled-write contract exists to enforce. end routes the write through the same lock → validate → commit → refresh → verify → unlock sequence a human uses, then confirms the commit actually changed. If it doesn’t confirm, end reports the failure rather than claiming success.

The “thin adapter” model matters because the begin/end logic should not be rewritten for each agent tool. The discipline is the same regardless of whether the agent is Claude Code on a laptop, Hermes on a cluster node, or a background cron worker — so the logic lives in one place, and each harness gets a thin wrapper that invokes it. Adding a new agent type means writing a new adapter, not reimplementing the discipline.

One thing worth calling out explicitly: the begin skill in this playbook was updated after publication to use a generated context digest instead of the original hand-maintained manifest. The digest (agents/context-digest.md) is regenerated automatically at the end of each session and contains a compact card-catalog of every vault page. Reading one file gives the agent a full map of the vault; reading the manifest required three separate file reads plus manual maintenance. If you’re adapting this skill to your own vault, build the digest pattern from the start — it scales much better.

Prerequisites

• A Git vault mounted or checked out locally (~/wiki).
• The controlled-writer lock (canonical-writer-lock.py) from the writer-lock playbook, on PATH.
• An agent harness (a CLI agent, a chat assistant, a background worker) whose startup you can hook.

Notes

• Substitute your own values before running any line — this playbook uses example stand-ins. Replace $HOME/wiki / ~/wiki (your vault path) and the script/tooling paths. Adapt begin/end to your own agent harness.
• Fail closed is the point. If the agent cannot prove it is reading current canonical state — vault unreachable, or an index commit that disagrees with HEAD — it must stop, not guess. Stale-but-confident is exactly the failure a knowledge base exists to prevent; don’t reintroduce it at the AI layer.
• begin loads the smallest connected context, not the whole vault. Start from a manifest of stable entry points and follow only to the pages the task touches. Cold start is about global awareness, not maximal ingestion.
• end never does a raw commit. It routes every write through the same lock → validate → commit → refresh → verify → unlock contract a human uses, then checks the commit changed. If the canonical commit can’t be verified afterward, do not claim the write landed.
• Adapters are thin on purpose. The begin/end logic is tool-agnostic; each harness just invokes it. That way a new agent inherits the same discipline for free.
• Mark tested: true only after running a full begin → task → end cycle, including a forced stale-index case, on your own vault.