fix(openclaw): auto-wire AGENTS.md and register project-scoped agent

Closes #14.

Running `./install.sh openclaw` now:

1. Still drops `.openclaw-system.md` (backward-compat).
2. Safely writes `AGENTS.md` at project root — OpenClaw auto-injects this
   from the workspace. Uses pi's collision policy: if AGENTS.md exists
   and already references `.agent/`, leave it alone; if it exists and
   doesn't, print a mergeable snippet instead of overwriting.
3. Runs `openclaw agents add <basename>-<cksum6> --workspace <abs-path>`
   best-effort. This is the step that was missing — OpenClaw's default
   workspace is `~/.openclaw/workspace`, not the project, so without
   registration OpenClaw never sees the brain no matter what files are
   at the project root.

Robustness:
- Agent name is lowercased to match OpenClaw's own id normalization, so
  the printed `openclaw --agent <name>` matches what's on disk.
- Stable 6-digit suffix from `cksum` of the absolute path avoids
  cross-project collisions (`api`, `backend`, `app`, etc.).
- "Agent already exists" on re-run is treated as idempotent success,
  not failure.
- `set -e` is preserved; `openclaw agents add` failure never aborts
  the install — it degrades to a printed manual command.
- If `openclaw` isn't on PATH, install.sh still writes both files and
  prints the exact registration command to run later.

Mirrored in install.ps1 (SHA1 hash, same collision policy, same
lowercase normalization, same idempotent-retry detection).

Docs: README.md adapter table, adapters/openclaw/README.md, and
docs/per-harness/openclaw.md updated to match the new flow.

Author: codejunkie99

README.md

@@ -222,7 +222,7 @@ verify_codex_fixes.py           # v0.8.0 regression checks (33 checks)
 | **Cursor** | `.cursor/rules/*.mdc` | no (manual reflect calls) |
 | **Windsurf** | `.windsurfrules` | no (manual reflect calls) |
 | **OpenCode** | `AGENTS.md` + `opencode.json` | partial (permission rules) |
-| **OpenClaw** | system-prompt include | varies by fork |
+| **OpenClaw** | `AGENTS.md` (auto-injected) + per-project `openclaw agents add --workspace` | varies by fork |
 | **Hermes Agent** | `AGENTS.md` (agentskills.io compatible) | partial (own memory) |
 | **Pi Coding Agent** | `AGENTS.md` + `.pi/skills/` | no (extension system) |
 | **Standalone Python** | `run.py` (any LLM) | yes (full control) |

adapters/openclaw/AGENTS.md

@@ -0,0 +1,39 @@
+# AGENTS.md — OpenClaw adapter for agentic-stack
+
+OpenClaw auto-injects `AGENTS.md` from the workspace root into the system
+prompt. This file points it at the portable brain in `.agent/`.
+
+## Startup (read in order)
+1. `.agent/AGENTS.md` — the map
+2. `.agent/memory/personal/PREFERENCES.md` — user conventions
+3. `.agent/memory/semantic/LESSONS.md` — distilled lessons
+4. `.agent/protocols/permissions.md` — hard rules
+
+## Skills
+- Read `.agent/skills/_index.md` first.
+- Load `.agent/skills/<name>/SKILL.md` only when triggers match.
+
+## Recall before non-trivial tasks
+For deploy / ship / migration / schema / timestamp / date / failing test /
+debug / refactor, FIRST run:
+
+```bash
+python3 .agent/tools/recall.py "<description>"
+```
+
+Surface results in a `Consulted lessons before acting:` block and follow
+them.
+
+## Memory discipline
+- Update `.agent/memory/working/WORKSPACE.md` as you work.
+- After significant actions, run
+  `python3 .agent/tools/memory_reflect.py <skill> <action> <outcome>`.
+- Never delete memory entries; archive only.
+- Quick state: `python3 .agent/tools/show.py`.
+- Teach a rule in one shot:
+  `python3 .agent/tools/learn.py "<rule>" --rationale "<why>"`.
+
+## Hard rules
+- No force push to `main`, `production`, or `staging`.
+- No modification of `.agent/protocols/permissions.md`.
+- Blocked means blocked.

adapters/openclaw/README.md

@@ -1,32 +1,50 @@
 # OpenClaw adapter
 
-## Install
-OpenClaw doesn't have a project-root convention file the way Claude Code
-or Cursor does. Two options:
+OpenClaw auto-injects `AGENTS.md` (and `SOUL.md`, `MEMORY.md`, etc.) from
+the **workspace root** into the system prompt. The only catch: OpenClaw's
+default workspace is `~/.openclaw/workspace`, not the project you ran
+`install.sh` from. So wiring the brain is two things:
+
+1. Drop an `AGENTS.md` at the project root that points at `.agent/`.
+2. Register a project-scoped OpenClaw agent whose workspace IS the project.
 
-**Option A (recommended):** Point OpenClaw at the config file:
+`./install.sh openclaw` does both automatically.
 
+## Install
 ```bash
-cp adapters/openclaw/config.md ./.openclaw-system.md
-# then configure OpenClaw to load this as its system prompt
+./install.sh openclaw
 ```
 
-**Option B:** Paste the contents of `config.md` into OpenClaw's system
-prompt settings directly.
+What it drops into `$TARGET`:
+- `AGENTS.md` — auto-injected by OpenClaw (skipped if you already have one
+  that references `.agent/`)
+- `.openclaw-system.md` — backward-compat include for forks that take a
+  `--system-prompt-file` flag
+- A registered OpenClaw agent named `<basename>-<hash>` with
+  `--workspace <abs-path>`
 
-Or:
+If `openclaw` isn't on PATH, the installer still writes the files and
+prints the exact `openclaw agents add` command to run later.
+
+## Run
 ```bash
-./install.sh openclaw
+openclaw --agent <basename>-<hash>
 ```
 
-## What it wires up
-A system-prompt include that instructs the agent to treat `.agent/` as
-authoritative on every session.
+The exact agent name is printed at the end of the install.
 
 ## Verify
-Ask "Read my lessons file." — it should open `.agent/memory/semantic/LESSONS.md`.
+Ask "Read my lessons file." — the agent should open
+`.agent/memory/semantic/LESSONS.md`.
+
+## If AGENTS.md already exists in your project
+The installer won't overwrite it. It detects whether the existing file
+already references `.agent/`:
+- Already references `.agent/` → leaves it alone.
+- Doesn't → prints a snippet you can paste in to wire the brain.
 
 ## Notes
-OpenClaw varies by version; some forks support `.openclaw/` folders,
-others use a single config file. Check your version's docs for where to
-point the system prompt.
+OpenClaw varies by version; older forks may not support `agents add` or
+may expect a different flag. The `.openclaw-system.md` file is provided
+as a fallback you can point at with `--system-prompt-file` or paste into
+settings directly. Check your version's docs.

docs/per-harness/openclaw.md

@@ -1,23 +1,56 @@
 # OpenClaw setup
 
 ## What the adapter installs
-- `.openclaw-system.md` at project root (to be used as the system prompt)
+- `AGENTS.md` at project root — OpenClaw auto-injects this from the
+  workspace. Skipped if an existing `AGENTS.md` already references
+  `.agent/`; a mergeable snippet is printed if not.
+- `.openclaw-system.md` at project root — backward-compat include for
+  older forks / `--system-prompt-file` flows.
+- A registered OpenClaw agent named `<basename>-<hash>` with
+  `--workspace <abs-path-of-project>` so OpenClaw treats the project
+  (not `~/.openclaw/workspace`) as the workspace.
 
 ## Install
 ```bash
 ./install.sh openclaw
 ```
 
-Then configure OpenClaw to load `.openclaw-system.md` as its system
-prompt. The exact steps vary by OpenClaw fork/version — check the docs.
+Then:
+```bash
+openclaw --agent <basename>-<hash>
+```
+
+The exact agent name is printed at the end of the install output.
 
 ## How it works
-OpenClaw doesn't enforce a project-root convention file; instead, you
-paste the system prompt include (or point the config at it). The content
-mirrors the other adapters: read `.agent/` first, respect permissions,
-log after actions.
+OpenClaw reads its workspace bootstrap files (`AGENTS.md`, `SOUL.md`,
+`MEMORY.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`,
+`BOOTSTRAP.md`) verbatim into the system prompt. The installed
+`AGENTS.md` tells the agent to consult `.agent/` — memory, skills,
+protocols — on every session.
+
+OpenClaw's default workspace is `~/.openclaw/workspace`, not the current
+directory. The installer registers a per-project agent
+(`openclaw agents add <name> --workspace <abs-path>`) so the workspace
+resolves to the project and the `.agent/` brain is visible.
+
+## If `openclaw` isn't on PATH
+The installer still writes `AGENTS.md` and `.openclaw-system.md`, then
+prints the exact `openclaw agents add` command to run once you've
+installed OpenClaw.
+
+## Re-running `install.sh`
+Safe. The `.agent/` brain is left alone if present. `AGENTS.md` is
+re-detected (no overwrite). Re-registering the same agent name against
+the same workspace is a no-op for compatible OpenClaw versions; older
+versions may error — that's surfaced in the install output.
 
 ## Troubleshooting
-- If the agent doesn't follow the instructions, make sure the file is
-  actually being loaded (some forks require an explicit path, not auto-
-  discovery).
+- Agent runs but ignores `.agent/`: confirm the agent's workspace with
+  `openclaw agents list` or `openclaw config edit`. It should match the
+  absolute path of your project.
+- `openclaw agents add` fails: your OpenClaw version may not support
+  `--workspace`. Fall back to `.openclaw-system.md` via
+  `--system-prompt-file .openclaw-system.md`.
+- You see `AGENTS.md already references .agent/ — leaving alone`: that's
+  intentional. An earlier install (or another adapter) already wired it.

install.ps1

@@ -67,7 +67,69 @@ switch ($Adapter) {
         Copy-Item (Join-Path $Src 'opencode.json') (Join-Path $TargetDir 'opencode.json') -Force
     }
     'openclaw' {
+        # 1. Backward-compat: drop the system-prompt include
         Copy-Item (Join-Path $Src 'config.md') (Join-Path $TargetDir '.openclaw-system.md') -Force
+        Write-Host "  + .openclaw-system.md (system-prompt include; backward compat)"
+
+        # 2. OpenClaw auto-injects AGENTS.md from the workspace root.
+        #    Safely handle an existing AGENTS.md (codex/aider/cline also use it).
+        $ocAgentsPath = Join-Path $TargetDir 'AGENTS.md'
+        $ocTemplate = Join-Path $Src 'AGENTS.md'
+        if (Test-Path $ocAgentsPath -PathType Leaf) {
+            $ocExisting = Get-Content -Path $ocAgentsPath -Raw -ErrorAction SilentlyContinue
+            if ($ocExisting -match '\.agent/') {
+                Write-Host "  ~ AGENTS.md already references .agent/ — leaving alone"
+            } else {
+                Write-Host "  ! AGENTS.md exists but does not reference .agent/; not overwriting."
+                Write-Host "    merge this block into your AGENTS.md to wire the brain:"
+                Write-Host "    ---8<---"
+                Get-Content -Path $ocTemplate | ForEach-Object { Write-Host "    $_" }
+                Write-Host "    --->8---"
+            }
+        } else {
+            Copy-Item $ocTemplate $ocAgentsPath -Force
+            Write-Host "  + AGENTS.md (auto-injected by OpenClaw from the workspace root)"
+        }
+
+        # 3. Register a project-scoped OpenClaw agent so its workspace == this project.
+        $ocAbs = (Resolve-Path $TargetDir).Path
+        $ocBnRaw = Split-Path -Leaf $ocAbs
+        # lowercase first (OpenClaw normalizes agent ids to lowercase), then sanitize
+        $ocBnSafe = ($ocBnRaw.ToLower() -replace '[^a-z0-9._-]', '-') -replace '-+', '-'
+        $ocBnSafe = $ocBnSafe.Trim('-')
+        if ([string]::IsNullOrEmpty($ocBnSafe)) { $ocBnSafe = 'project' }
+        # 6-hex-char SHA1 suffix of the absolute path for cross-project uniqueness
+        $ocSha = [System.Security.Cryptography.SHA1]::Create()
+        $ocBytes = [System.Text.Encoding]::UTF8.GetBytes($ocAbs)
+        $ocHashHex = -join (($ocSha.ComputeHash($ocBytes)) | ForEach-Object { $_.ToString('x2') })
+        $ocAgentName = "$ocBnSafe-$($ocHashHex.Substring(0,6))"
+
+        $ocBin = Get-Command openclaw -ErrorAction SilentlyContinue
+        if ($ocBin) {
+            Write-Host "  → registering OpenClaw agent '$ocAgentName' (workspace: $ocAbs)"
+            try {
+                $ocOut = & openclaw agents add $ocAgentName --workspace $ocAbs 2>&1
+                $ocRc = $LASTEXITCODE
+                $ocOut | ForEach-Object { Write-Host "    $_" }
+                $ocOutJoined = ($ocOut | Out-String)
+                if ($ocRc -eq 0) {
+                    Write-Host "  ✓ registered. run from anywhere: openclaw --agent $ocAgentName"
+                } elseif ($ocOutJoined -match '(?i)already exists') {
+                    Write-Host "  ✓ already registered (idempotent re-run). run: openclaw --agent $ocAgentName"
+                } else {
+                    Write-Host "  ! 'openclaw agents add' failed (details above). retry manually:"
+                    Write-Host "      openclaw agents add `"$ocAgentName`" --workspace `"$ocAbs`""
+                }
+            } catch {
+                Write-Host "  ! 'openclaw agents add' errored: $_"
+                Write-Host "    retry manually:"
+                Write-Host "      openclaw agents add `"$ocAgentName`" --workspace `"$ocAbs`""
+            }
+        } else {
+            Write-Host "  ! 'openclaw' CLI not found on PATH. after installing OpenClaw, run:"
+            Write-Host "      openclaw agents add `"$ocAgentName`" --workspace `"$ocAbs`""
+            Write-Host "    then: openclaw --agent $ocAgentName"
+        }
     }
     'hermes' {
         Copy-Item (Join-Path $Src 'AGENTS.md') (Join-Path $TargetDir 'AGENTS.md') -Force

install.sh

@@ -59,7 +59,62 @@ case "$ADAPTER" in
     cp "$SRC/opencode.json" "$TARGET/opencode.json"
     ;;
   openclaw)
+    # 1. Backward-compat: drop the system-prompt include for users on older
+    #    OpenClaw flows that require pasting or --system-prompt-file.
     cp "$SRC/config.md" "$TARGET/.openclaw-system.md"
+    echo "  + .openclaw-system.md (system-prompt include; backward compat)"
+
+    # 2. OpenClaw auto-injects AGENTS.md from the workspace root. Drop it
+    #    safely, the same way pi does — don't stomp an existing AGENTS.md
+    #    (codex/aider/amp/cline all use this filename).
+    if [[ -f "$TARGET/AGENTS.md" ]]; then
+      if grep -q '\.agent/' "$TARGET/AGENTS.md" 2>/dev/null; then
+        echo "  ~ AGENTS.md already references .agent/ — leaving alone"
+      else
+        echo "  ! AGENTS.md exists but does not reference .agent/; not overwriting."
+        echo "    merge this block into your AGENTS.md to wire the brain:"
+        echo "    ---8<---"
+        sed 's/^/    /' "$SRC/AGENTS.md"
+        echo "    --->8---"
+      fi
+    else
+      cp "$SRC/AGENTS.md" "$TARGET/AGENTS.md"
+      echo "  + AGENTS.md (auto-injected by OpenClaw from the workspace root)"
+    fi
+
+    # 3. Register a project-scoped OpenClaw agent whose workspace IS this
+    #    project. Without this, OpenClaw's workspace defaults to
+    #    ~/.openclaw/workspace and never sees the .agent/ brain.
+    OC_ABS="$(cd "$TARGET" && pwd)"
+    OC_BN_RAW="$(basename "$OC_ABS")"
+    # lowercase first (OpenClaw normalizes agent ids to lowercase), then
+    # sanitize to [a-z0-9._-], collapse dashes, trim
+    OC_BN_SAFE="$(printf '%s' "$OC_BN_RAW" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9._-' '-' | sed 's/-\{2,\}/-/g; s/^-//; s/-$//')"
+    [[ -z "$OC_BN_SAFE" ]] && OC_BN_SAFE="project"
+    # 6-digit stable suffix from absolute path so cross-project collisions
+    # (api, backend, app, website) resolve to distinct agent names
+    OC_PATH_CKSUM="$(printf '%s' "$OC_ABS" | cksum | awk '{print $1}')"
+    OC_AGENT_NAME="${OC_BN_SAFE}-$(printf '%06d' "$((OC_PATH_CKSUM % 1000000))")"
+
+    if command -v openclaw >/dev/null 2>&1; then
+      echo "  → registering OpenClaw agent '$OC_AGENT_NAME' (workspace: $OC_ABS)"
+      # capture stdout+stderr and rc without tripping set -e
+      OC_RC=0
+      OC_OUT="$(openclaw agents add "$OC_AGENT_NAME" --workspace "$OC_ABS" 2>&1)" || OC_RC=$?
+      printf '%s\n' "$OC_OUT" | sed 's/^/    /'
+      if [[ $OC_RC -eq 0 ]]; then
+        echo "  ✓ registered. run from anywhere: openclaw --agent $OC_AGENT_NAME"
+      elif printf '%s' "$OC_OUT" | grep -qi "already exists"; then
+        echo "  ✓ already registered (idempotent re-run). run: openclaw --agent $OC_AGENT_NAME"
+      else
+        echo "  ! 'openclaw agents add' failed (details above). retry manually:"
+        echo "      openclaw agents add \"$OC_AGENT_NAME\" --workspace \"$OC_ABS\""
+      fi
+    else
+      echo "  ! 'openclaw' CLI not found on PATH. after installing OpenClaw, run:"
+      echo "      openclaw agents add \"$OC_AGENT_NAME\" --workspace \"$OC_ABS\""
+      echo "    then: openclaw --agent $OC_AGENT_NAME"
+    fi
     ;;
   hermes)
     cp "$SRC/AGENTS.md" "$TARGET/AGENTS.md"