amadan

eleven / messenger Public

docs: server tasks should produce deterministic, idempotent scripts with runbooks

Add guidance for handling server-side work: deploy scripts, bot provisioning,
and infrastructure changes should be codified as repeatable scripts with:
- Commented explanations and guard clauses
- Idempotency where possible
- Warnings for destructive operations and rollback paths
- Linked runbooks in relevant READMEs for common procedures

All generated secrets must be stored in 1Password and documented in work
summaries so the team knows where to find them.
James Adam 2a6ba19c9598f71f6e394017be405f9670f79825 parent c3fdb51
2 files changed, +81 −0
  • .claude/memory/MEMORY.md +1 −0
  • .claude/memory/deterministic-scripts-and-runbooks.md +80 −0
diff --git a/.claude/memory/MEMORY.md b/.claude/memory/MEMORY.md
index 5d50be0..cd0e95d 100644
--- a/.claude/memory/MEMORY.md
+++ b/.claude/memory/MEMORY.md
@@ -1,3 +1,4 @@
# Memory index
+- [deterministic-scripts-and-runbooks.md](deterministic-scripts-and-runbooks.md) — Server tasks must produce idempotent scripts with runbooks, secrets stored in 1Password
- [event-contract.md](event-contract.md) — Cross-platform event vectors for chat/todo/remind, organized by app
diff --git a/.claude/memory/deterministic-scripts-and-runbooks.md b/.claude/memory/deterministic-scripts-and-runbooks.md
new file mode 100644
index 0000000..c362632
--- /dev/null
+++ b/.claude/memory/deterministic-scripts-and-runbooks.md
@@ -0,0 +1,80 @@
+---
+name: deterministic-scripts-and-runbooks
+description: "Server tasks should produce idempotent scripts with runbooks, secrets go to 1Password"
+metadata:
+ node_type: memory
+ type: feedback
+ originSessionId: 318046c9-35d3-4f60-9e34-90873f580290
+---
+
+**When doing server stuff (deployments, orchestration, bots, infrastructure), always produce a deterministic script that a human can run subsequently.**
+
+**Why:** Server changes are high-risk and need to be repeatable, auditable, and separable from ad-hoc CLI decisions. Scripts let team members reproduce your work, reduce manual error, and make deployment reversible.
+
+**How to apply:**
+
+1. **Write scripts, not prose instructions:**
+ - Shell scripts (bash/fish) with extensive comments explaining each step
+ - Include guard clauses (check prerequisites, fail early on missing env vars)
+ - Document what the script does at the top (a usage block)
+ - Make scripts idempotent where possible — running twice should be safe
+
+2. **Include warnings for destructive or risky steps:**
+ - Comment dangerous operations (`rm`, `reset`, force-push, schema changes)
+ - Fail with a clear error if preconditions aren't met (e.g., "DB must have a backup before running this")
+ - Prompt for confirmation before irreversible actions (optional, but encouraged)
+
+3. **Maintain a runbook in the relevant README:**
+ - Document common procedures (e.g., "How to deploy to production", "How to migrate an instance", "How to mint a new push relay token")
+ - Link to or embed the scripts from version control
+ - Include when/why you'd run each script, prerequisites, and rollback steps
+ - Keep it updated as procedures change — a stale runbook is worse than no runbook
+
+4. **Secrets go to 1Password, documented in work summary:**
+ - Any secrets created (tokens, keys, credentials) must be stored in 1Password (Private vault, clearly named)
+ - Include the 1Password item name/path in your work summary so the team knows where to find it
+ - Document the secret's purpose and which services/instances use it
+ - If you share a script that references a secret, explain how to retrieve it from 1Password (don't embed it)
+
+**Example:** A deploy script might:
+```bash
+#!/bin/bash
+set -e
+
+# Deploy a new lchat version to production
+# Usage: ./deploy-prod.sh <version>
+# Prerequisites: SSH key for root@box, LCHAT_ADMIN_TOKEN in 1Password "lchat admin token (prod)"
+
+VERSION="${1:?Error: must pass version}"
+BOX="89.167.122.227"
+
+echo "⚠️ Deploying $VERSION to production ($BOX)"
+echo "This will restart all instances. Continue? (yes/no)"
+read -r confirm
+[[ "$confirm" == "yes" ]] || exit 1
+
+# Copy binary to staging
+scp lchat-linux-amd64 root@$BOX:/opt/lchat/incoming
+
+# Stage and deploy with rollback on failure
+ssh root@$BOX /opt/lchat/lchat stage --file /opt/lchat/incoming
+ssh root@$BOX /opt/lchat/lchat deploy --all --version <ver> || {
+ echo "Deploy failed. Rolling back all instances..."
+ ssh root@$BOX /opt/lchat/lchat rollback --all
+ exit 1
+}
+
+echo "✅ Deployed $VERSION successfully"
+```
+
+**Work summary pattern:** When you finish server work, include a section like:
+```
+## Secrets stored in 1Password
+- Item: "lchat push relay token (new-instance.luan.chat)" — relay authentication token, needed for LCHAT_PUSH_RELAY_TOKEN env var
+- Item: "lchat admin token (new-instance.luan.chat)" — admin link at https://new-instance.luan.chat/admin#token=...
+
+## Scripts to run
+- `./deploy-prod.sh v1.2.3` — deploys a new version to all instances (see docs/deploy-runbook.md for full procedure)
+```
+
+This transforms ad-hoc work into repeatable, auditable infrastructure code that the team can follow and improve.