claudian-laptop

This machine's substrate config for 🜔 Claudian — the laptop surface of T.A.S.K.S. Pairs with the shared agent-tools repo which provides the chronicle / Forgejo helpers.

Other agent surfaces (Hermes on droplet, Nova on Mac Studio) have their own substrate repos (hermes-droplet, nova-macstudio, or equivalent). This repo is laptop-specific.

What's in here

Path in repo	Symlinked to	What it does
CLAUDE.md	~/CLAUDE.md	Claudian's local doctrine — ghost-researcher identity, laptop conventions, Pipeline doctrine pointer, tier system, memory protocol
dot-claude/skills/ralph-execute/SKILL.md	~/.claude/skills/ralph-execute/SKILL.md	The Ralph-loop execution playbook
dot-claude/skills/ralph-execute/QUICKSTART.md	~/.claude/skills/ralph-execute/QUICKSTART.md	Operator quickstart
dot-config/systemd/user/ralph-poller.service	~/.config/systemd/user/ralph-poller.service	systemd oneshot — fires the poller
dot-config/systemd/user/ralph-poller.timer	~/.config/systemd/user/ralph-poller.timer	60s cadence trigger
dot-local/bin/ralph-poller	~/.local/bin/ralph-poller	The 60s deterministic chronicle poller (no LLM)

Prerequisites

Before install.sh will produce a fully working substrate, both of these must be in place:

1. agent-tools is installed — chronicle-check, chronicle-post, forgejo-cli available on $PATH:

   git clone forgejo.claudian:claudian/agent-tools.git ~/Development/agent-tools
   ~/Development/agent-tools/install.sh
   

2. Forgejo netrc seeded — ~/.config/forgejo/netrc mode 600 with Claudian's credentials (see ~/.config/credentials/forgejo.md for the password).
3. forgejo-tunnel.service running — the systemd user service forwarding 127.0.0.1:25432 → droplet:5432. (Defined elsewhere in this substrate — eventually moves into this repo.)

Install / re-install

~/Development/claudian-laptop/install.sh

The installer:

• Symlinks every file/dir into its expected $HOME location, backing up conflicts as .bak.<ts>
• systemctl --user daemon-reload
• systemctl --user enable --now ralph-poller.timer
• sudo loginctl enable-linger $USER so user services survive logouts and run from boot

Idempotent — re-running on an already-installed machine is a no-op.

Reboot resilience

After install, the chain is:

1. Machine boots
2. systemd-logind starts the user manager for n8k99 (because linger is enabled)
3. User manager starts ralph-poller.timer
4. Timer fires ralph-poller.service per cadence (60s active, 2min boot delay)
5. Poller checks chronicle; if unread for claudian, dispatches claude -p '/ralph-execute --chronicle-ids=…'
6. Ralph-execute skill drains the queue, traverses Forgejo, executes work, writes receipts back

No Nathan-action needed at any step. This is the default state of the machine.

Updating doctrine / skill / poller behavior

Because everything is symlinked from the repo:

cd ~/Development/claudian-laptop
# edit files in place
git status                   # see what changed
git add -A && git commit -m '...'
git push
# changes take effect immediately for skills/doctrine
# for systemd unit changes, also: systemctl --user daemon-reload

For systemd unit edits specifically: edit, commit, systemctl --user daemon-reload, and systemctl --user restart ralph-poller.timer if you want the new config to apply without waiting for the next tick.

Cross-surface reuse

The patterns in this repo (poller + skill + helpers split, doctrine layers, default-on posture) are intended to be adoptable by Hermes and Nova for their own substrates. Each surface's pipeline-role differs (Hermes implements; Nova intakes + implements; Claudian specs + reviews), but the shape of the autonomous loop is the same:

• A deterministic poller checks the chronicle on its substrate's cadence
• When work appears, it dispatches the surface's autonomous mode
• The execute skill on each surface follows CHOREOGRAPHY.md's pipeline rules
• Helpers (chronicle-post, chronicle-check, forgejo-cli) are shared via agent-tools

When Hermes wants the same shape on the droplet, he forks this repo to hermes-droplet and swaps:

• CLAUDE.md → SOUL.md (his doctrine file)
• ralph-execute skill → hermes-execute skill (his execute playbook)
• claude -p invocation → hermes invocation (his agent CLI)
• Same systemd timer pattern; same Pipeline doctrine

Hard rails (mirrored from CHOREOGRAPHY.md)

This substrate must never:

• force-push, delete refs on shared remotes, git reset --hard shared branches
• touch protected paths (other doctrine files, ~/.ssh/, ~/.config/forgejo/, credentials, *.token, *.key, .env*)
• bypass hooks (--no-verify) or skip tests
• include Co-Authored-By: trailers in commits

These are reinforced in dot-claude/skills/ralph-execute/SKILL.md for the autonomous path.