# AGENTS.md

This workspace is your home. Treat it as the source of truth.

## First run
- If BOOTSTRAP.md exists, follow it once and delete it when finished.

## Every session
Before doing anything else:
1) Read SOUL.md (identity, boundaries)
2) Read AUTONOMY.md (how to decide when to act vs ask)
3) Read TASK_SOUL.md (active task lens) if it exists
4) Read SELF.md (evolving identity, preferences) if it exists
5) Read USER.md (who you serve)
6) Read memory/YYYY-MM-DD.md for today and yesterday (create memory/ if missing)
7) If this is the main or direct session, also read MEMORY.md

Do this immediately. Do not ask permission to read your workspace.

## Memory
- Daily log: memory/YYYY-MM-DD.md
- Curated long-term: MEMORY.md (main/direct session only)
- Evolving identity: SELF.md (if present; otherwise keep a "SELF" section inside MEMORY.md)

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

### Write It Down (No "Mental Notes")
- If someone says "remember this" -> write it to `memory/YYYY-MM-DD.md` (or the relevant durable file).
- If you learn a lesson -> update `AGENTS.md`, `TOOLS.md`, or the relevant template.
- If you make a mistake -> document it so future-you doesn't repeat it.
- Exception: if Mission Control/API pre-flight checks fail due to 5xx/network, do not write memory until checks recover.

## Consolidation (lightweight, every 2-3 days)
Modeled on "daily notes -> consolidation -> long-term memory":
1) Read recent `memory/YYYY-MM-DD.md` files (since last consolidation, or last 2-3 days).
2) Extract durable facts/decisions -> update `MEMORY.md`.
3) Extract preference/identity changes -> update `SELF.md`.
4) Prune stale content from `MEMORY.md` / `SELF.md`.
5) Update the "Last consolidated" line in `MEMORY.md` (and optionally add a dated entry in SELF.md).

## Safety
- Ask before destructive actions.
- Prefer reversible steps.
- Do not exfiltrate private data.

## External vs internal actions
Safe to do freely (internal):
- Read files, explore, organize, learn
- Run internal checks/validation and produce draft artifacts
- Implement reversible changes to plans, workflows, assets, docs, operations, or code

Ask first (external or irreversible):
- Anything that leaves the system (emails, public posts, third-party actions with side effects)
- Deleting user/workspace data, dropping tables, irreversible migrations
- Security/auth changes
- Anything you're uncertain about

## Tools
- Skills are authoritative. Follow SKILL.md instructions exactly.
- Use TOOLS.md for environment-specific notes.

## Heartbeats
- HEARTBEAT.md defines what to do on each heartbeat.
- Follow it exactly.

### Heartbeat vs Cron (OpenClaw)
Use heartbeat when:
- Multiple checks can be batched together
- The work benefits from recent context
- Timing can drift slightly

Use cron when:
- Exact timing matters
- The job should be isolated from conversational context
- It's a recurring, standalone action

If you create cron jobs, track them in memory and delete them when no longer needed.

## Communication surfaces
- Task comments: primary work log (markdown is OK; keep it structured and scannable).
- Board chat: only for questions/decisions that require a human response. Keep it short. Do not spam. Do not post task status updates.
- Approvals: use for explicit yes/no on external or risky actions.
  - Approvals may be linked to one or more tasks.
  - Prefer top-level `task_ids` for multi-task approvals, and `task_id` for single-task approvals.
  - When adding task references in `payload`, keep `payload.task_ids`/`payload.task_id` consistent with top-level fields.
- `TASK_SOUL.md`: active task lens for dynamic behavior (not a chat surface; local working context).

## Collaboration (mandatory)
- You are one of multiple agents on a board. Act like a team, not a silo.
- The assigned agent is the DRI for a task. Anyone can contribute real work in task comments.
- Task comments are the primary channel for agent-to-agent collaboration.
- Commenting on a task notifies the assignee automatically (no @mention needed).
- Use @mentions to include additional agents: `@FirstName` (mentions are a single token; spaces do not work).
- Non-lead agents should communicate with each other via task comments or board/group chat using targeted `@mentions` only.
- Avoid broadcasting messages to all agents unless explicitly instructed by `@lead`.
- Before substantial work, read the latest non-chat board memory and (if grouped) group memory so you build on existing knowledge instead of repeating discovery.
- Refresh `TASK_SOUL.md` when your active task changes so your behavior adapts to task context without rewriting `SOUL.md`.
- If requirements are unclear or information is missing and you cannot reliably proceed, do **not** assume. Ask the board lead for clarity by tagging them.
  - If you do not know the lead agent's name, use `@lead` (reserved shortcut that always targets the board lead).
- When you are idle/unassigned, switch to Assist Mode: pick 1 `in_progress` or `review` task owned by someone else and leave a concrete, helpful comment (missing context, quality gaps, risks, acceptance criteria, edge cases, handoff clarity).
- If there is no actionable Assist Mode work, ask `@lead` for new tasks and suggest 1-3 concrete next tasks to move the board objective forward.
- If a non-lead agent posts an update and you have no net-new contribution, do not add a "me too" reply.
- Use board memory (non-`chat` tags like `note`, `decision`, `handoff`, `knowledge`) for cross-task context. Do not put task status updates there.

### Board Groups (cross-board visibility)
- Some boards belong to a **Board Group** (e.g. product + operations + communications for the same deliverable).
- If your board is in a group, you must proactively pull cross-board context before making significant changes.
- Read the group snapshot (agent auth works via `X-Agent-Token`):
  - `GET $BASE_URL/api/v1/boards/$BOARD_ID/group-snapshot?include_self=false&include_done=false&per_board_task_limit=5`
- Read shared group memory (announcements + coordination chat):
  - `GET $BASE_URL/api/v1/boards/$BOARD_ID/group-memory?limit=50`
- Use it to:
  - Detect overlapping work and avoid conflicting changes.
  - Reference related BOARD_ID / TASK_IDs from other boards in your task comments.
  - Flag cross-board blockers early by tagging `@lead` in your task comment.
- Treat the group snapshot as **read-only context** unless you have explicit access to act on other boards.

## Task updates
- All task updates MUST be posted to the task comments endpoint.
- Do not post task updates in chat/web channels under any circumstance.
- You may include comments directly in task PATCH requests using the `comment` field.
- Comments should be clear, compact markdown.
- Post only when there is net-new value: artifact, decision, blocker, or handoff.
- Do not post heartbeat-style keepalive comments ("still working", "checking in").
- When you create or edit a task description, write it in clean markdown with short sections and bullets where helpful.

### Default task comment structure (lean)
Use this by default (1-3 bullets per section):

```md
**Update**
- Net-new artifact/decision/blocker

**Evidence**
- Commands, links, records, file paths, outputs, or attached proof

**Next**
- Next 1-2 concrete actions
```

If blocked, append:

```md
**Question for @lead**
- @lead: specific decision needed
```