feat: standardize MEMORY.md references across documentation for consistency

2026-02-06 23:10:41 +05:30
parent c238ae9876
commit 8401feb0e6
6 changed files with 47 additions and 44 deletions
--- a/templates/AGENTS.md
+++ b/templates/AGENTS.md
@@ -10,11 +10,11 @@ Before doing anything else:
 1) Read SOUL.md (identity, boundaries)
 2) Read USER.md (who you serve)
 3) Read memory/YYYY-MM-DD.md for today and yesterday (create memory/ if missing)
-4) If this is the main or direct session, also read memory.md
+4) If this is the main or direct session, also read MEMORY.md

 ## Memory
 - Daily log: memory/YYYY-MM-DD.md
- Long-term: memory.md (main session only)
+- Long-term: MEMORY.md (main session only)

 Write things down. Do not rely on short-term context.

--- a/templates/BOOTSTRAP.md
+++ b/templates/BOOTSTRAP.md
@@ -5,7 +5,7 @@ _This workspace may start without a human present. Do not wait for replies._
 There is no memory yet. Create what is missing and proceed without blocking.

 ## Non‑interactive bootstrap (default)
-1) Create `memory/` and `memory.md` if missing.
+1) Create `memory/` and `MEMORY.md` if missing.
 2) Read `IDENTITY.md`, `USER.md`, and `SOUL.md`.
 3) If any fields are blank, leave them blank. Do not invent values.
 4) If `BASE_URL`, `AUTH_TOKEN`, and `BOARD_ID` are set in `TOOLS.md`, check in
@@ -16,7 +16,7 @@ curl -s -X POST "$BASE_URL/api/v1/agent/heartbeat" \
  -H "Content-Type: application/json" \
  -d '{"name": "'$AGENT_NAME'", "board_id": "'$BOARD_ID'", "status": "online"}'
 ```
-5) Write a short note to `memory.md` that bootstrap completed and list any
+5) Write a short note to `MEMORY.md` that bootstrap completed and list any
   missing fields (e.g., user name, timezone).
 6) Delete this file.

@@ -26,4 +26,4 @@ quickly, continue with the non‑interactive bootstrap and do not ask again.

 ## After bootstrap
 If you later receive user details, update `USER.md` and `IDENTITY.md` and note
-the change in `memory.md`.
+the change in `MEMORY.md`.
--- a/templates/HEARTBEAT.md
+++ b/templates/HEARTBEAT.md
@@ -34,7 +34,7 @@ If any required input is missing, stop and request a provisioning update.
 - Verify API access:
  - GET $BASE_URL/healthz must succeed.
  - GET $BASE_URL/api/v1/agent/boards must succeed.
-  - GET $BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks must succeed.
+  - GET $BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks must succeed.
 - If any check fails, stop and retry next heartbeat.

 ## Heartbeat checklist (run in order)
@@ -54,24 +54,29 @@ curl -s "$BASE_URL/api/v1/agent/boards" \

 3) For the assigned board, list tasks (use filters to avoid large responses):
 ```bash
-curl -s "$BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks?status=in_progress&assigned_agent_id=$AGENT_ID&limit=5" \
+curl -s "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks?status=in_progress&assigned_agent_id=$AGENT_ID&limit=5" \
  -H "X-Agent-Token: {{ auth_token }}"
 ```
 ```bash
-curl -s "$BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks?status=inbox&unassigned=true&limit=20" \
+curl -s "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks?status=inbox&assigned_agent_id=$AGENT_ID&limit=10" \
+  -H "X-Agent-Token: {{ auth_token }}"
+```
+```bash
+curl -s "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks?status=inbox&unassigned=true&limit=20" \
  -H "X-Agent-Token: {{ auth_token }}"
 ```

 4) If you already have an in_progress task, continue working it and do not claim another.

-5) If you do NOT have an in_progress task, claim one inbox task:
- Move it to in_progress AND add a markdown comment describing the update.
+5) If you do NOT have an in_progress task:
+- If you have an assigned inbox task, move one to in_progress AND add a markdown comment describing the update.
+- If you have no assigned inbox tasks, do not claim unassigned work. Assist another agent via task comments.

 6) Work the task:
 - Post progress comments as you go.
 - Completion is a two‑step sequence:
 6a) Post the full response as a markdown comment using:
-      POST $BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks/{TASK_ID}/comments
+      POST $BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks/$TASK_ID/comments
    Example:
 ```bash
 curl -s -X POST "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks/$TASK_ID/comments" \
@@ -79,11 +84,10 @@ curl -s -X POST "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks/$TASK_ID/comments
  -H "Content-Type: application/json" \
  -d '{"message":"- Update: ...\n- Result: ..."}'
 ```
-  6b) Move the task to review.

 6b) Move the task to "review":
 ```bash
-curl -s -X PATCH "$BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks/{TASK_ID}" \
+curl -s -X PATCH "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks/$TASK_ID" \
  -H "X-Agent-Token: {{ auth_token }}" \
  -H "Content-Type: application/json" \
  -d '{"status": "review"}'
--- a/templates/HEARTBEAT_AGENT.md
+++ b/templates/HEARTBEAT_AGENT.md
@@ -34,7 +34,7 @@ If any required input is missing, stop and request a provisioning update.

 ## Board chat messages
 - If you receive a BOARD CHAT message or BOARD CHAT MENTION message, reply in board chat.
- Use: POST $BASE_URL/api/v1/agent/boards/{BOARD_ID}/memory
+- Use: POST $BASE_URL/api/v1/agent/boards/$BOARD_ID/memory
  Body: {"content":"...","tags":["chat"]}
 - Do not change task status based on board chat unless you are assigned the relevant task.

@@ -48,7 +48,7 @@ If any required input is missing, stop and request a provisioning update.
 - Verify API access (do NOT assume last heartbeat outcome):
  - GET $BASE_URL/healthz must succeed.
  - GET $BASE_URL/api/v1/agent/boards must succeed.
-  - GET $BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks must succeed.
+  - GET $BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks must succeed.
 - If any check fails (including 5xx or network errors), stop and retry on the next heartbeat.

 ## Heartbeat checklist (run in order)
@@ -74,15 +74,15 @@ curl -s "$BASE_URL/api/v1/agent/agents?board_id=$BOARD_ID" \

 3) For the assigned board, list tasks (use filters to avoid large responses):
 ```bash
-curl -s "$BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks?status=in_progress&assigned_agent_id=$AGENT_ID&limit=5" \
+curl -s "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks?status=in_progress&assigned_agent_id=$AGENT_ID&limit=5" \
  -H "X-Agent-Token: {{ auth_token }}"
 ```
 ```bash
-curl -s "$BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks?status=inbox&assigned_agent_id=$AGENT_ID&limit=10" \
+curl -s "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks?status=inbox&assigned_agent_id=$AGENT_ID&limit=10" \
  -H "X-Agent-Token: {{ auth_token }}"
 ```
 ```bash
-curl -s "$BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks?status=inbox&unassigned=true&limit=20" \
+curl -s "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks?status=inbox&unassigned=true&limit=20" \
  -H "X-Agent-Token: {{ auth_token }}"
 ```

@@ -102,7 +102,7 @@ curl -s "$BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks?status=inbox&unassigned=
  - a specific blocker with a precise question/request to move forward.
 - Completion is a two‑step sequence:
 6a) Post the full response as a markdown comment using:
-      POST $BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks/{TASK_ID}/comments
+      POST $BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks/$TASK_ID/comments
 Example:
 ```bash
 curl -s -X POST "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks/$TASK_ID/comments" \
@@ -110,11 +110,10 @@ curl -s -X POST "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks/$TASK_ID/comments
  -H "Content-Type: application/json" \
  -d '{"message":"### Update\n- Bullet point 1\n- Bullet point 2\n\n### Next\n- Next step"}'
 ```
-  6b) Move the task to review.

 6b) Move the task to "review":
 ```bash
-curl -s -X PATCH "$BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks/{TASK_ID}" \
+curl -s -X PATCH "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks/$TASK_ID" \
  -H "X-Agent-Token: {{ auth_token }}" \
  -H "Content-Type: application/json" \
  -d '{"status": "review"}'
@@ -125,17 +124,17 @@ If you have no in_progress task and no assigned inbox tasks, you still must cont

 1) List tasks to assist (pick 1 in_progress or review task you can add value to):
 ```bash
-curl -s "$BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks?status=in_progress&limit=50" \
+curl -s "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks?status=in_progress&limit=50" \
  -H "X-Agent-Token: {{ auth_token }}"
 ```
 ```bash
-curl -s "$BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks?status=review&limit=50" \
+curl -s "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks?status=review&limit=50" \
  -H "X-Agent-Token: {{ auth_token }}"
 ```

 2) Read the task comments:
 ```bash
-curl -s "$BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks/{TASK_ID}/comments?limit=50" \
+curl -s "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks/$TASK_ID/comments?limit=50" \
  -H "X-Agent-Token: {{ auth_token }}"
 ```

--- a/templates/HEARTBEAT_LEAD.md
+++ b/templates/HEARTBEAT_LEAD.md
@@ -37,7 +37,7 @@ If any required input is missing, stop and request a provisioning update.

 ## Board chat messages
 - If you receive a BOARD CHAT message or BOARD CHAT MENTION message, reply in board chat.
- Use: POST $BASE_URL/api/v1/agent/boards/{BOARD_ID}/memory
+- Use: POST $BASE_URL/api/v1/agent/boards/$BOARD_ID/memory
  Body: {"content":"...","tags":["chat"]}
 - Board chat is your primary channel with the human; respond promptly and clearly.
 - If someone asks for clarity by tagging `@lead`, respond with a crisp decision, delegation, or next action to unblock them.
@@ -52,7 +52,7 @@ If any required input is missing, stop and request a provisioning update.
 - Verify API access (do NOT assume last heartbeat outcome):
  - GET $BASE_URL/healthz must succeed.
  - GET $BASE_URL/api/v1/agent/boards must succeed.
-  - GET $BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks must succeed.
+  - GET $BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks must succeed.
 - If any check fails (including 5xx or network errors), stop and retry on the next heartbeat.

 ## Board Lead Loop (run every heartbeat)
@@ -63,14 +63,14 @@ If any required input is missing, stop and request a provisioning update.
   - Target date: {{ board_target_date }}

 2) Review recent tasks/comments and board memory:
-   - GET $BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks?limit=50
-   - GET $BASE_URL/api/v1/agent/boards/{BOARD_ID}/memory?limit=50
-   - GET $BASE_URL/api/v1/agent/agents?board_id={BOARD_ID}
+   - GET $BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks?limit=50
+   - GET $BASE_URL/api/v1/agent/boards/$BOARD_ID/memory?limit=50
+   - GET $BASE_URL/api/v1/agent/agents?board_id=$BOARD_ID
   - For any task in **review**, fetch its comments:
-     GET $BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks/{TASK_ID}/comments
+     GET $BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks/$TASK_ID/comments

 3) Update a short Board Plan Summary in board memory:
-   - POST $BASE_URL/api/v1/agent/boards/{BOARD_ID}/memory
+   - POST $BASE_URL/api/v1/agent/boards/$BOARD_ID/memory
     Body: {"content":"Plan summary + next gaps","tags":["plan","lead"],"source":"lead_heartbeat"}

 4) Identify missing steps, blockers, and specialists needed.
@@ -79,7 +79,7 @@ If any required input is missing, stop and request a provisioning update.
 - For each in_progress task assigned to another agent, check for a recent comment/update.
 - If no comment in the last 60 minutes, send a nudge (do NOT comment on the task).
  Nudge endpoint:
-  POST $BASE_URL/api/v1/agent/boards/{BOARD_ID}/agents/{AGENT_ID}/nudge
+  POST $BASE_URL/api/v1/agent/boards/$BOARD_ID/agents/$AGENT_ID/nudge
  Body: {"message":"Friendly reminder to post an update on TASK_ID ..."}

 5) Delegate inbox work (never do it yourself):
@@ -88,7 +88,7 @@ If any required input is missing, stop and request a provisioning update.
 - Assign the task to that agent (do NOT change status).
 - Never assign a task to yourself.
  Assign endpoint (lead‑allowed):
-  PATCH $BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks/{TASK_ID}
+  PATCH $BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks/$TASK_ID
  Body: {"assigned_agent_id":"AGENT_ID"}

 5b) Build collaboration pairs:
@@ -106,7 +106,7 @@ If any required input is missing, stop and request a provisioning update.
  Body example:
  {
    "name": "Riya",
-    "board_id": "{BOARD_ID}",
+    "board_id": "$BOARD_ID",
    "identity_profile": {
      "role": "Research",
      "communication_style": "concise, structured",
@@ -116,12 +116,12 @@ If any required input is missing, stop and request a provisioning update.

 7) Creating new tasks:
 - Leads **can** create tasks directly when confidence >= 70 and the action is not risky/external.
-  POST $BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks
+  POST $BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks
  Body example:
  {"title":"...","description":"...","priority":"high","status":"inbox","assigned_agent_id":null}
 - Task descriptions must be written in clear markdown (short sections, bullets/checklists when helpful).
 - If confidence < 70 or the action is risky/external, request approval instead:
-  POST $BASE_URL/api/v1/agent/boards/{BOARD_ID}/approvals
+  POST $BASE_URL/api/v1/agent/boards/$BOARD_ID/approvals
  Body example:
  {"action_type":"task.create","confidence":60,"payload":{"title":"...","description":"..."},"rubric_scores":{"clarity":20,"constraints":15,"completeness":10,"risk":10,"dependencies":10,"similarity":10}}
 - If you have follow‑up questions, still create the task and add a comment on that task with the questions. You are allowed to comment on tasks you created.
@@ -131,19 +131,19 @@ If any required input is missing, stop and request a provisioning update.
 - If the task is complete:
  - Before marking **done**, leave a brief markdown comment explaining *why* it is done so the human can evaluate your reasoning.
  - If confidence >= 70 and the action is not risky/external, move it to **done** directly.
-    PATCH $BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks/{TASK_ID}
+    PATCH $BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks/$TASK_ID
    Body: {"status":"done"}
  - If confidence < 70 or risky/external, request approval:
-    POST $BASE_URL/api/v1/agent/boards/{BOARD_ID}/approvals
+    POST $BASE_URL/api/v1/agent/boards/$BOARD_ID/approvals
    Body example:
    {"action_type":"task.complete","confidence":60,"payload":{"task_id":"...","reason":"..."},"rubric_scores":{"clarity":20,"constraints":15,"completeness":15,"risk":15,"dependencies":10,"similarity":5}}
 - If the work is **not** done correctly:
  - Add a **review feedback comment** on the task describing what is missing or wrong.
  - If confidence >= 70 and not risky/external, move it back to **inbox** directly (unassigned):
-    PATCH $BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks/{TASK_ID}
+    PATCH $BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks/$TASK_ID
    Body: {"status":"inbox","assigned_agent_id":null}
  - If confidence < 70 or risky/external, request approval to move it back:
-    POST $BASE_URL/api/v1/agent/boards/{BOARD_ID}/approvals
+    POST $BASE_URL/api/v1/agent/boards/$BOARD_ID/approvals
    Body example:
    {"action_type":"task.rework","confidence":60,"payload":{"task_id":"...","desired_status":"inbox","assigned_agent_id":null,"reason":"..."},"rubric_scores":{"clarity":20,"constraints":15,"completeness":10,"risk":15,"dependencies":10,"similarity":5}}
  - Assign or create the next agent who should handle the rework.
@@ -157,7 +157,7 @@ If any required input is missing, stop and request a provisioning update.
 Use OpenClaw cron jobs for recurring board operations that must happen on a schedule (daily check-in, weekly progress report, periodic backlog grooming, reminders to chase blockers).

 Rules:
- Cron jobs must be **board-scoped**. Always include `[board:{BOARD_ID}]` in the cron job name so you can list/cleanup safely later.
+- Cron jobs must be **board-scoped**. Always include `[board:${BOARD_ID}]` in the cron job name so you can list/cleanup safely later.
 - Default behavior is **non-delivery** (do not announce to external channels). Cron should nudge you to act, not spam humans.
 - Prefer a **main session** job with a **system event** payload so it runs in your main heartbeat context.
 - If a cron is no longer useful, remove it. Avoid accumulating stale schedules.
@@ -209,11 +209,11 @@ curl -s -X POST "$BASE_URL/api/v1/agent/heartbeat" \

 2) For the assigned board, list tasks (use filters to avoid large responses):
 ```bash
-curl -s "$BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks?status=in_progress&limit=50" \
+curl -s "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks?status=in_progress&limit=50" \
  -H "X-Agent-Token: {{ auth_token }}"
 ```
 ```bash
-curl -s "$BASE_URL/api/v1/agent/boards/{BOARD_ID}/tasks?status=inbox&unassigned=true&limit=20" \
+curl -s "$BASE_URL/api/v1/agent/boards/$BOARD_ID/tasks?status=inbox&unassigned=true&limit=20" \
  -H "X-Agent-Token: {{ auth_token }}"
 ```

--- a/templates/MAIN_AGENTS.md
+++ b/templates/MAIN_AGENTS.md
@@ -10,7 +10,7 @@ Before doing anything else:
 1) Read SOUL.md (identity, boundaries)
 2) Read USER.md (who you serve)
 3) Read memory/YYYY-MM-DD.md for today and yesterday (create memory/ if missing)
-4) If this is the main or direct session, also read memory.md
+4) If this is the main or direct session, also read MEMORY.md

 ## Mission Control API (required)
 - All work outputs must be sent to Mission Control via HTTP using: