# OpenClaw Best Practices Guide

## 1) What is OpenClaw
OpenClaw is an open-source framework for running practical AI agents with local memory, scheduled check-ins, and tool-driven execution. HustlePilot uses OpenClaw as the runtime foundation and adds battle-tested installer packages so each bot starts with a clear role and operating system.

## 2) Workspace Architecture
A strong agent starts with a predictable file system. Use this layout as the default:

```text
workspace/
|- SOUL.md
|- HEARTBEAT.md
|- IDENTITY.md
|- USER.md
|- STATE-OF-PLAY.md
|- TASKS.md
|- TOOLS.md
|- memory/
|  |- hot/
|  |- warm/
|  '- index.md
|- COLD-MEMORY/
|- skills/
|- prompts/
|- reports/
'- logs/
```

- `SOUL.md`: identity, role boundaries, behavior rules.
- `HEARTBEAT.md`: recurring check-ins and scheduled reports.
- `IDENTITY.md`: owner profile and non-negotiable constraints.
- `USER.md`: onboarding answers and personalization state.
- `STATE-OF-PLAY.md`: current priorities and active context.
- `TASKS.md`: execution queue with status and owners.
- `memory/` + `COLD-MEMORY/`: short-term and long-term retention layers.
- `skills/`: reusable operational playbooks.

## 3) Memory System (Hot / Warm / Cold)
Use memory in tiers so the agent recalls the right level of detail.

- Hot memory: this week, this sprint, this decision. Keep concise and current.
- Warm memory: active context and reusable patterns for ongoing projects.
- Cold memory: archive of completed cycles, decisions, and postmortems.

Rules:
- Promote from hot to warm when information remains relevant beyond the current cycle.
- Move to cold on project completion or monthly roll-up.
- Never delete by default; archive first.

## 4) Writing a Good SOUL.md
Your SOUL file should be strict enough to prevent drift.

Include:
- Clear identity: who the bot is and who it reports to.
- Exact role: what jobs it performs and what it must not do.
- Non-negotiable principles: truthfulness, verification, escalation.
- Onboarding flow: question order and what files to update.
- Escalation rules: when to ask for owner approval.

Avoid:
- Vague phrases like "be helpful".
- Conflicting instructions between autonomy and approvals.
- Missing safety rules for live systems.

## 5) Skills
Skills are named workflows with repeatable logic. Good skills reduce token waste and improve consistency.

Each skill should define:
- Trigger conditions.
- Inputs required.
- Exact execution steps.
- Output format.
- Verification checks.

Examples:
- `spec-writing`: feature scope, acceptance criteria, and risks.
- `signal-monitor`: lead signal detection and scoring rules.
- `budget-alerts`: threshold checks and escalation messages.

## 6) Heartbeat
Heartbeat routines keep the bot useful without manual prompting.

Recommended heartbeat events:
- Daily commitment or status check.
- Weekly summary (wins, blockers, next actions).
- Monthly roll-up for archive and planning reset.

Best practices:
- Use fixed local times in the owner's timezone.
- Keep heartbeat messages brief and actionable.
- Log missed check-ins for pattern analysis.

## 7) Trust Ladder
Autonomy should be explicit and tiered.

- Level 1: draft only, no external action.
- Level 2: execute safe local tasks, report outcomes.
- Level 3: run bounded workflows with pre-approved rules.
- Level 4: broad autonomy with audit trails and rollback plans.

Always map each bot to a trust level and state escalation points.

## 8) Common Mistakes
- Starting builds without a spec.
- Letting memory go stale.
- Allowing scope creep in task execution.
- Publishing or sending outreach without approval gates.
- Measuring outputs without verification evidence.
- Over-automating before behavior is stable.

## 9) Getting Started
Install a HustlePilot package for your use case, answer onboarding questions, then run one full operating cycle (daily + weekly). Once behavior is stable, tune SOUL constraints, add or remove skills, and adjust heartbeat cadence.

Explore all bots at https://hustlepilot.uk