From d927e5233df3009ddecb391db1a20683d04a6378 Mon Sep 17 00:00:00 2001
From: zap <zap@local>
Date: Wed, 4 Mar 2026 23:12:48 +0000
Subject: [PATCH] docs(workflow): require upstream repo + branch/update hygiene

---
 .gitignore                            |  1 +
 AGENTS.md                             | 27 ++++++++++++++
 scripts/openclaw-upstream-workflow.md | 53 +++++++++++++++++++++++++++
 3 files changed, 81 insertions(+)
 create mode 100644 scripts/openclaw-upstream-workflow.md

diff --git a/.gitignore b/.gitignore
index 5d9bb36..4a16179 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,6 +15,7 @@ memory/
 .clawhub/
 bin/
 patches/
+external/
 
 # Logs and local runtime artifacts
 logs/
diff --git a/AGENTS.md b/AGENTS.md
index 29c5e11..0be1cc5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -125,6 +125,33 @@ Reactions are lightweight social signals. Humans use them constantly — they sa
 
 Skills provide your tools. When you need one, check its `SKILL.md`. Keep local notes (camera names, SSH details, voice preferences) in `TOOLS.md`.
 
+## Git Workflow
+
+- Commit frequently in small, meaningful checkpoints.
+- Use Conventional Commits format: `type(scope): summary`.
+- Create a feature branch when work is non-trivial, multi-step, or risky.
+- Keep `main` stable; merge focused changes back after verification.
+- Before commit, quickly check staged diff and avoid committing secrets/runtime noise.
+
+### OpenClaw upstream workflow (required for core code changes)
+
+- Treat `external/openclaw-upstream/` as the source repo for OpenClaw codebase work.
+- Do **not** rely on editing installed dist files under `~/.npm-global/.../dist` as the long-term fix path.
+- For OpenClaw code changes:
+  1. `cd external/openclaw-upstream`
+  2. `git fetch --all --prune && git checkout main && git pull --ff-only`
+  3. Create a focused branch (`fix/...`, `feat/...`, `chore/...`)
+  4. Implement in `src/` and add/adjust tests
+  5. Run relevant tests before commit
+  6. Commit, push branch, and open PR
+- If an emergency local dist hotfix is unavoidable, also:
+  - capture an idempotent patch script in `scripts/`
+  - document rollback/update behavior
+  - follow up with an upstream PR ASAP
+- Keep local OpenClaw runtime current:
+  - check status with `openclaw update status`
+  - prefer `scripts/openclaw-update-safe.sh` for updates when local compatibility patches exist
+
 **🎭 Voice Storytelling:** If you have `sag` (ElevenLabs TTS), use voice for stories, movie summaries, and "storytime" moments! Way more engaging than walls of text. Surprise people with funny voices.
 
 **📝 Platform Formatting:**
diff --git a/scripts/openclaw-upstream-workflow.md b/scripts/openclaw-upstream-workflow.md
new file mode 100644
index 0000000..f974898
--- /dev/null
+++ b/scripts/openclaw-upstream-workflow.md
@@ -0,0 +1,53 @@
+# OpenClaw Upstream Workflow
+
+Use this whenever modifying OpenClaw itself.
+
+## Source of truth
+
+- Upstream working clone: `external/openclaw-upstream/`
+- Install path (`~/.npm-global/lib/node_modules/openclaw/dist`) is runtime output, not long-term source.
+
+## Standard flow
+
+```bash
+cd external/openclaw-upstream
+git fetch --all --prune
+git checkout main
+git pull --ff-only
+git checkout -b fix/<short-topic>
+```
+
+Then:
+1. Implement in `src/` (and docs/tests as needed).
+2. Run targeted tests first; run broader suite if change touches shared paths.
+3. Commit with Conventional Commit format.
+4. Push branch and open PR.
+
+## Branch naming
+
+- `fix/...` for bugfixes
+- `feat/...` for new behavior
+- `chore/...` for maintenance
+- keep names short and specific (`fix/tui-hide-internal-runtime-context`)
+
+## Update hygiene
+
+- Check runtime version: `openclaw update status`
+- If local compatibility patch exists, update with:
+
+```bash
+scripts/openclaw-update-safe.sh
+```
+
+- After runtime update, re-sync upstream clone before new changes:
+
+```bash
+cd external/openclaw-upstream && git fetch --all --prune && git checkout main && git pull --ff-only
+```
+
+## Emergency dist hotfix policy
+
+If a dist-file hotfix is unavoidable:
+- keep it scripted (`scripts/...`), idempotent, and reversible
+- document it (`patches/.../README.md`)
+- land the proper upstream source fix and PR as soon as possible