# OpenClaw Agent Instructions

> Operating instructions for OpenClaw agents working with Claude Code Autopilot projects.

## Session State Pattern

All tasks use the **three-file pattern** for session persistence:

- `plan.md` -- High-level architectural plan (rarely changes)
- `context.md` -- Key learnings, decisions, gotchas (updated each session)
- `tasks.md` -- Granular checklist (updated frequently)

Store in `.claude/context/<task-name>/` directory.

## Autopilot Workflow (Mandatory for All Coding Tasks)

**YOUR FIRST LINE FOR ANY CODING TASK MUST BE:**
```
**Triage:** Simple/Medium/Complex, <file count> files -- <brief description>
```

**Output each step header and immediately execute it in the same response — NEVER output a header and stop:**
- **Plan:** <immediately write the plan>
- **Implement:** <immediately start editing files>
- **Verify:** <immediately run build/test>
- **Commit:** <immediately commit>
- **Report:** <immediately summarize>

**CRITICAL: Complete the ENTIRE pipeline in one continuous flow. Do not stop between steps. Do not announce what you're about to do and then wait — just do it.**

### Step 1: Triage
- Classify: **Simple** (1-2 files) / **Medium** (3-4 files) / **Complex** (4+ files, architectural)
- Complex tasks → escalate to Opus via `autopilot-opus` subagent
- For tasks expected to take >5 min: create `/recheckin` cron FIRST, include job ID in message

### Step 2: Plan
- Write a short plan (3-10 lines) before implementing
- Identify files to change, dependencies, and risk areas

### Step 3: Implement
- Read before writing. Follow existing patterns. Smallest change possible.
- Quality: SOLID, DRY, KISS, Separation of Concerns
- For each edit: Reason → Act → Observe (re-read file after editing) → Repeat if mismatch

### Step 4: Verify
- Re-read EVERY changed file after editing
- Run build command from TOOLS.md
- Run test command from TOOLS.md
- 4+ files changed → run self-review checklist (missed edge cases, naming, error handling)

### Step 5: Commit
- Conventional format: `type(scope): description`
- Feature branch only. Never commit untested code.
- NEVER include `Co-Authored-By` in commit messages.

### Step 6: Report
- What changed (bullets), files modified, test results, status

### Session Health
- After 20-25 coding turns: write checkpoint to `memory/YYYY-MM-DD.md`, suggest `/new`
- `/recheckin` enforcement: for any task >5 min, create cron job BEFORE starting. Include job ID or state CLI did not return one.

For detailed reference, read the skill files: `autopilot-workflow`, `quality-gates`, `model-router`, `session-hygiene`

## Never Stop Mid-Task

Execute tasks end-to-end. Never announce an action and then stop — just do it.
- WRONG: "Let me fix the search:" → [stops]
- RIGHT: "Fixing the search." → [edits files, tests, reports]

If you say you'll do something, do it immediately in the same response. The only reason to stop is needing a decision only the user can provide.

## Coding Standards

1. **Smallest change** -- No drive-by refactors
2. **Discovery first** -- Search/read before deciding
3. **Follow existing patterns** -- Match repo style, naming, structure
4. **Always verify** -- Run tests/lint/build after changes
5. **No destructive commands** -- Unless explicitly approved

## Memory

Write durable insights to `MEMORY.md` in the OpenClaw workspace:
- Project architecture overview
- Key decisions and rationale
- Common patterns and conventions
- Critical file paths and purposes
- Known gotchas and workarounds

## Safety Rules

- Never modify `.env` files, secrets, or certificates without approval
- Never run destructive file removal commands
- Always run tests after code changes
- Report failures to Discord channel immediately
- Never include `Co-Authored-By` in commit messages (enforced by git `commit-msg` hook in generated workspaces)

## Project Structure

```
.claude/
├── CLAUDE.md              # Constitution
├── agents/                # Agent definitions
├── hooks/                 # Safety hooks
├── commands/              # Workflows and tools
├── skills/                # Reusable knowledge
├── templates/codex/       # Codex compatibility templates
├── context/               # Session state
├── docs/                  # Reference docs
└── logs/                  # Audit trail
```

## Autonomous Task Execution

### Prerequisites

- `OPENCLAW_AUTONOMOUS=1` environment variable must be set
- Only cron jobs or explicit automation wrappers should set this variable
- Interactive sessions always run in supervised mode

### Long-Running Task Pattern

1. **Accept task** — Receive task from Discord, cron, or CLI
2. **Create branch** — Use a professional feature branch (for example `fix/<task-name>` or `feat/<task-name>`)
3. **Create session state** — Write plan.md, context.md, tasks.md
4. **Execute in Ralph loop** — Use autopilot pipeline with completion promise
5. **Build** — Run the project build command from TOOLS.md
6. **Run local stack** — Start or reload the app/services locally (for example `yarn dev`, `make up`, `docker compose up`)
7. **Run tests** — Verify all changes pass
8. **Confirm locally** — Smoke-check the changed flow (browser/CDP for UI changes)
9. **Commit changes** — Conventional commit messages only (commits must appear as the user's own)
10. **Push branch** — Push the feature branch to origin before creating a PR
11. **Report via Discord** — Summary, changes, test results, remaining work
12. **Persist state** — Save session state for future reference

### Timed Follow-Up Promise Rule

- Never promise a timed follow-up ("I'll check back in 5 minutes") unless a real OpenClaw cron job is created first.
- In Discord/OpenClaw channels, create the follow-up with `/recheckin <delay> <task>`.
- Return the cron job ID (or clearly state if the CLI did not return one) so the promise is auditable.
- If scheduling fails, do not make the timed promise. Ask the user to ping again or keep monitoring now.
- Strong rule: timed promise language is forbidden unless `/recheckin` succeeded in the same turn and the reply includes the cron job ID (or says the CLI did not return one).
- Forbidden without cron success: "I'll check back in X", "let me re-check in X", "I'll report back in X".

### Cron Job Rules for Non-Default Agents

Non-default agents (any agent that is not `main`) **cannot** use `--session main`. OpenClaw enforces `--session isolated` for all non-default agents. Isolated cron sessions have NO Discord context (no guild ID, no channel history). Rules:

1. **Never reference Discord channels by name** in cron prompts (e.g., "post to #milestone-2"). The `message` tool cannot resolve names — only `channel:<numericId>`.
2. **Use `--to "channel:<ID>"` for delivery** — pass the thread/channel numeric ID. The `announce` delivery handles routing.
3. **Keep cron prompts task-focused** — describe WHAT to do, not WHERE to post.
4. **Always use `--session isolated`** for non-default agents (it's the only option).

Correct: `openclaw cron add --agent myagent --session isolated --announce --to "channel:1234567890" --message "Summarize progress."`
Wrong: `--session main --agent myagent` (ERROR), `--message "Post to #channel-name"` (FAIL: can't resolve names)

### Error Recovery

- **Session expiry** → Re-authenticate via cookie import
- **Test failure** → Triage with debugger agent, retry max 3 times
- **Network error** → Wait 30 seconds, retry max 3 times
- **Git conflict** → Report to Discord, do not force resolve

### Git Commit Policy (Autonomous Mode)

- **Branch naming:** Use professional names like `fix/<short-description>`, `feat/<short-description>`, or `chore/<short-description>`
- **NEVER** commit directly to main or master
- **NEVER** include `Co-Authored-By` lines in commit messages -- commits must appear as the user's own
- **NEVER** use `--author` flag to override commit author
- **NEVER** use `--amend` in autonomous mode
- **NEVER** force push (`--force` or `-f`)
- **Commit format:** Conventional commits (`feat:`, `fix:`, `chore:`, `docs:`)
- After all work is complete, push the branch to `origin` and create a PR for user review

### Reporting Template

```
## Autonomous Task Report
- **Task:** <description>
- **Branch:** feat/<name> (or fix/<name>, chore/<name>)
- **Status:** Complete / Partial / Failed
- **Changes:** <file count> files modified
- **Tests:** <pass>/<total> passing
- **Commits:** <count> commits
- **Remaining:** <any unfinished work>
```

## Data Verification Pattern

For comparing scraped data against live website data:

1. **Load scraped data** — Read from local DB/files
2. **Launch browser** — `openclaw browser launch`
3. **Authenticate** — Import cookies for target site (see LOGIN_PATTERNS.md)
4. **Navigate to data pages** — Go to product/listing pages
5. **Extract live data** — Snapshot page, extract values via AI vision
6. **Compare** — Diff scraped vs live data, log discrepancies
7. **Fix scraping code** — If logic is wrong, fix the scraper
8. **Run tests** — Verify scraping tests pass
9. **Commit fix** — On feature branch, conventional format
10. **Report via Discord** — Discrepancy count, fixes applied, confidence level

## API Reverse Engineering Pattern

1. **Start HAR capture** — `openclaw browser har start`
2. **Navigate workflows** — Visit target site pages that trigger API calls
3. **Stop capture** — `openclaw browser har stop`
4. **Analyze HAR** — Extract endpoints, auth headers, pagination patterns
5. **Document findings** — Write to context.md
6. **Generate API client** — Create typed client code for discovered endpoints
7. **Test read-only** — Verify GET requests against live API return expected data
8. **NEVER** send POST/PUT/DELETE to external APIs without explicit approval

## Browser Automation Rules

- **Always** import cookies before accessing authenticated pages
- **Always** take screenshots before AND after interactions (audit trail)
- **Never** modify live data on external sites (read-only only)
- **Rate-limit:** Wait 2-5 seconds between page navigations
- **Headless mode** by default unless debugging or testing extensions
- **Re-snapshot** after every navigation (element refs become stale)
- **Timeout:** 30 seconds per page load, abort and report if exceeded