goal-agent

# goal-agent ## Overview The goal-agent skill creates a workspace that turns an OpenClaw agent into a focused, autonomous optimizer. You give it a goal and a shell command that measures progress — the agent does the rest, iterating heartbeat by heartbeat, learning what works and what doesn't. --- ## Usage ### Step 1: Collect inputs | Input | Flag | Required | Default | |-------|------|----------|---------| | Goal description | `--goal` | ✅ | — | | Metric command (returns a number) | `--metric` | ✅ | — | | Target value | `--target` | ✅ | — | | Direction (up/down) | `--direction` | ❌ | `up` | | Safety constraints | `--constraints` | ❌ | `None` | | Max iterations | `--max-iterations` | ❌ | `50` | | Output directory | `--output-dir` | ❌ | `./` | ### Step 2: Run scaffold.sh ```bash bash ~/clawd/skills/goal-agent/scripts/scaffold.sh \ --goal "Increase daily active users to 100" \ --metric "cat /tmp/my-metric.json | jq '.dau'" \ --target 100 \ --direction up \ --constraints "Do not modify the database schema. Stay within $50/day budget." \ --max-iterations 30 \ --output-dir ~/clawd/goals/dau-growth ``` This generates the following files in `--output-dir`: - `GOAL.md` — goal definition, iteration counter, history table - `STRATEGY.md` — current approach, hypotheses, next action - `LEARNINGS.md` — rules extracted from experience - `HEARTBEAT.md` — the feedback loop instructions (replaces main HEARTBEAT.md) - `evaluate.sh` — runnable metric evaluator ### Step 3: Activate the feedback loop The generated `HEARTBEAT.md` **is** the goal-agent loop. Each heartbeat, the agent: 1. Measures the metric 2. Compares against target and history 3. Reflects on what worked/didn't 4. Decides the next action 5. Acts 6. Records results 7. Adapts strategy **To activate:** Copy `HEARTBEAT.md` to `~/clawd/HEARTBEAT.md` (or symlink it): ```bash cp ~/clawd/goals/dau-growth/HEARTBEAT.md ~/clawd/HEARTBEAT.md ``` ### Step 4: Deploy options **Option A — Current agent (fastest)** Copy all generated files into your workspace and activate HEARTBEAT.md as above. **Option B — Dedicated VM (cleanest)** Use the `spawn-agent` skill to create a fresh agent VM, then copy the goal workspace there: ```bash # On the new agent scp -r ~/clawd/goals/dau-growth/ ubuntu@new-agent:~/clawd/goals/ ssh ubuntu@new-agent "cp ~/clawd/goals/dau-growth/HEARTBEAT.md ~/clawd/HEARTBEAT.md" ``` --- ## Examples ### Example 1: Optimize test coverage ```bash bash ~/clawd/skills/goal-agent/scripts/scaffold.sh \ --goal "Increase test coverage to 80%" \ --metric "cd ~/myproject && npx jest --coverage --coverageReporters=text-summary 2>/dev/null | grep 'Statements' | grep -oP '\d+\.\d+(?=%)'" \ --target 80 \ --direction up \ --max-iterations 20 \ --output-dir ~/clawd/goals/test-coverage ``` ### Example 2: Reduce build time ```bash bash ~/clawd/skills/goal-agent/scripts/scaffold.sh \ --goal "Reduce build time to under 30 seconds" \ --metric "cd ~/myproject && time npm run build 2>&1 | grep real | grep -oP '\d+\.\d+'" \ --target 30 \ --direction down \ --constraints "Do not remove any build steps. Do not break production builds." \ --output-dir ~/clawd/goals/build-speed ``` ### Example 3: Grow social followers ```bash bash ~/clawd/skills/goal-agent/scripts/scaffold.sh \ --goal "Reach 500 Twitter followers" \ --metric "~/.openclaw/scripts/twitter-follower-count.sh" \ --target 500 \ --direction up \ --constraints "Only post authentic content. No follow-for-follow schemes." \ --output-dir ~/clawd/goals/twitter-growth ``` --- ## Safety & Sandboxing **Before activating a goal-agent loop, review these guidelines:** - **Review generated files before activating.** Always read the generated `HEARTBEAT.md` and `evaluate.sh` before copying them into your workspace. Confirm the metric command and constraints are what you intended. - **Use `--constraints` to limit scope.** The agent will only take actions within the constraints you define. Be explicit: "Only modify files in ~/myproject/src", "Do not make network requests", "Do not delete files". - **Set a low `--max-iterations` for first runs.** Start with 5-10 to observe behavior before allowing longer runs. - **Prefer dedicated VMs for autonomous goals.** Use `spawn-agent` to isolate goal-agents from your main workspace. This limits blast radius if the agent takes unexpected actions. - **Metric commands should be read-only.** The `--metric` command should only *measure* — never modify state. Use simple commands like `cat`, `wc`, `jq`, `grep`. - **The "Act" step is constrained by text, not code.** The agent follows the constraints you set in `--constraints`, but there is no programmatic sandbox. For high-stakes goals, combine with filesystem permissions, network egress controls, or a restricted user account. - **Monitor early iterations.** Check `GOAL.md` history after the first few heartbeats to verify the agent is behaving as expected. --- ## How it works The `HEARTBEAT.md` implements a tight cognitive loop: ``` Measure → Compare → Reflect → Decide → Act → Record → Adapt ↑___________________________________________________| ``` Each iteration, the agent reads its own history (`GOAL.md`), its current understanding (`STRATEGY.md`), and accumulated wisdom (`LEARNINGS.md`) before taking action. Over time it builds a library of what works for your specific goal. --- ## Files reference | File | Purpose | Agent modifies? | |------|---------|----------------| | `GOAL.md` | Source of truth: goal, metric, target, history | Status + History only | | `STRATEGY.md` | Current plan, hypotheses, next action | Yes (every iteration) | | `LEARNINGS.md` | Extracted rules and patterns | Yes (as it learns) | | `HEARTBEAT.md` | Loop instructions | No | | `evaluate.sh` | Runnable metric command | No | --- ## Skill location `~/clawd/skills/goal-agent/`