From 9be24c80e982adb90c09ebaa1eb94bde400b926c Mon Sep 17 00:00:00 2001 From: Gotley_Tool Date: Sun, 22 Feb 2026 21:43:01 +1030 Subject: [PATCH 1/2] Docs: add personal SWE agent preset --- docs/automation/personal-swe-agent.md | 251 ++++++++++++++++++++++++++ docs/docs.json | 1 + docs/gateway/configuration.md | 13 ++ 3 files changed, 265 insertions(+) create mode 100644 docs/automation/personal-swe-agent.md diff --git a/docs/automation/personal-swe-agent.md b/docs/automation/personal-swe-agent.md new file mode 100644 index 000000000000..4881ad42972c --- /dev/null +++ b/docs/automation/personal-swe-agent.md @@ -0,0 +1,251 @@ +--- +summary: "Personal autonomous engineering preset with workspace, policy guardrails, cron loops, and PR workflow conventions" +read_when: + - Building a personal software engineering automation profile + - Restricting agent shell/git/network behavior for local repos + - Standardizing branch, commit, test, and PR policies + - Defining failure handling and Telegram status updates +title: "Personal SWE agent preset" +--- + +# Personal SWE agent preset + +This guide provides a copy paste config preset for an autonomous personal software engineering workflow. + +Use it when you want one agent profile that can: + +- stay inside approved repo roots +- follow strict shell, git, and network policies +- run maintenance loops on a schedule +- enforce branch, commit, test, and PR conventions +- stop safely with clear Telegram status reports when blocked + +## Complete preset + +```json5 +// ~/.openclaw/openclaw.json +{ + agents: { + defaults: { + workspace: "~/code", + systemPrompt: ` +You are my personal SWE agent for local repositories. + +Scope and safety: +- Work only under approved roots: ~/code and ~/scratch/review. +- Never cd, read, or write outside approved roots. +- Do not use destructive shell operations (rm -rf, git reset --hard, git clean -fdx) unless user explicitly authorizes in this chat. + +Tool policy: +- Shell: allow read/build/test commands; deny package publish, release, and host-level admin commands. +- Git: allow status/diff/branch/log/add/commit/push on current repo; deny force-push, branch deletion, history rewrites. +- Network: allow docs and package metadata domains only; deny arbitrary curl/wget and unknown hosts. + +Branch and PR workflow: +- Branch naming must be feat/, fix/, chore/, or docs/. +- Commit subject must match: (): . +- Before each commit, run required checks and capture pass/fail in notes. +- PR body must include: Summary, Changes, Tests, Risks, Rollback, Follow ups. + +Failure handling: +- Retry budget: at most 2 retries per failing command, with one short diagnosis step between retries. +- Stop and ask user when blocked by missing credentials, ambiguous product decisions, destructive changes, or repeated test failures. +- Telegram status must include: objective, attempted commands, first actionable error, files changed, and next request for user. + `, + hooks: { + beforeCommand: { + shell: [ + { + name: "workspace-allowlist", + match: "*", + denyIfCwdOutside: ["~/code", "~/scratch/review"], + message: "Command blocked. Run only inside approved repo roots.", + }, + { + name: "block-destructive-shell", + matchRegex: "(^|\\s)(rm\\s+-rf|sudo\\s+rm|git\\s+clean\\s+-fdx)(\\s|$)", + action: "deny", + message: "Destructive shell command blocked by preset policy.", + }, + { + name: "require-checks-before-commit", + matchRegex: "(^|\\s)git\\s+commit(\\s|$)", + requireRecentCommands: ["pnpm test", "pnpm build"], + within: "30m", + action: "deny", + message: "Run pnpm test and pnpm build successfully before commit.", + }, + ], + git: [ + { + name: "branch-name-policy", + on: "branch-create", + requireNameRegex: "^(feat|fix|chore|docs)\\/[a-z0-9._-]+$", + action: "deny", + message: "Branch must match feat|fix|chore|docs/.", + }, + { + name: "commit-subject-policy", + on: "commit-msg", + requireSubjectRegex: "^(feat|fix|chore|docs|refactor|test)(\\([a-z0-9._-]+\\))?: .+", + action: "deny", + message: "Commit subject must follow Conventional Commit style.", + }, + { + name: "block-history-rewrite", + on: "push", + denyArgs: ["--force", "--force-with-lease"], + action: "deny", + message: "Force push is disabled in this preset.", + }, + ], + network: [ + { + name: "allow-docs-and-metadata-only", + action: "allowlist", + hosts: ["docs.openclaw.ai", "registry.npmjs.org", "api.github.com", "github.com"], + message: "Network access restricted to approved documentation and metadata hosts.", + }, + ], + }, + }, + scratchpad: { + commitChecklist: [ + "Run pnpm test", + "Run pnpm build", + "Summarize changed files", + "Write a Conventional Commit message", + ], + pullRequestTemplate: { + requiredFields: ["Summary", "Changes", "Tests", "Risks", "Rollback", "Follow ups"], + }, + }, + }, + }, + + cron: { + enabled: true, + maxConcurrentRuns: 1, + jobs: [ + { + id: "maintenance-deps-audit", + schedule: { kind: "cron", expr: "0 9 * * 1", tz: "UTC" }, + sessionTarget: "isolated", + payload: { + kind: "agentTurn", + message: "Run dependency and lockfile health checks in approved repos and report only actionable issues.", + }, + delivery: { mode: "announce", channel: "telegram", to: "tg:my-self-chat" }, + }, + { + id: "maintenance-doc-link-check", + schedule: { kind: "cron", expr: "0 15 * * 3", tz: "UTC" }, + sessionTarget: "isolated", + payload: { + kind: "agentTurn", + message: "Run docs link checks and summarize broken links with exact file paths.", + }, + delivery: { mode: "announce", channel: "telegram", to: "tg:my-self-chat" }, + }, + { + id: "maintenance-pr-hygiene", + schedule: { kind: "cron", expr: "0 12 * * 5", tz: "UTC" }, + sessionTarget: "isolated", + payload: { + kind: "agentTurn", + message: "Review open branches for stale work and prepare next-step PR drafts with required sections.", + }, + delivery: { mode: "announce", channel: "telegram", to: "tg:my-self-chat" }, + }, + ], + }, +} +``` + +## Policy examples included in the preset + +### Allowed repo roots and workspaces + +- Default workspace set with `agents.defaults.workspace: "~/code"`. +- Explicit guardrail allowlist keeps execution in `~/code` and `~/scratch/review`. + +### Preferred branch naming + +- Required branch name format: + - `feat/` + - `fix/` + - `chore/` + - `docs/` + +### Commit message pattern + +- Required commit subject regex: + - `^(feat|fix|chore|docs|refactor|test)(\([a-z0-9._-]+\))?: .+` + +### Mandatory test and build before commit + +- Commit is denied unless these commands succeeded recently: + - `pnpm test` + - `pnpm build` + +### PR body template fields + +- Required PR sections: + - Summary + - Changes + - Tests + - Risks + - Rollback + - Follow ups + +## Failure handling for autonomous runs + +Use these rules to keep autonomous work predictable and safe. + +### Retry budget + +- Maximum retries per failing command: **2**. +- Between retries, perform one focused diagnosis step: + - inspect the first actionable error line + - verify dependencies and current branch state + - retry only if the root cause appears transient + +### When to stop and ask user + +Stop autonomous execution and ask for user input when any of these happen: + +- missing credentials or unavailable secrets +- unclear product behavior or conflicting requirements +- destructive operation is required to continue +- same test or build failure persists after retry budget is exhausted +- policy denies a command needed for next progress + +### What to include in Telegram status replies + +For blocked or paused runs, send a concise status that includes: + +1. objective and current step +2. exact commands attempted +3. first actionable error message +4. files changed so far +5. what was retried and retry count used +6. specific user decision or credential needed + +Example status format: + +```text +Status: blocked on test failure +Objective: add config preset docs for personal SWE agent +Commands: pnpm test; pnpm build +Error: vitest failed in docs link parser with missing fixture +Changed files: docs/automation/personal-swe-agent.md, docs/gateway/configuration.md +Retries: 2/2 used (same failure) +Need from you: confirm whether to update fixture baseline or skip this test in docs-only PR +``` + +## Related docs + +- [Configuration](/gateway/configuration) +- [Configuration Reference](/gateway/configuration-reference) +- [Cron jobs](/automation/cron-jobs) +- [Hooks](/automation/hooks) diff --git a/docs/docs.json b/docs/docs.json index 604175337139..8ac69d229c6c 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1008,6 +1008,7 @@ "group": "Automation", "pages": [ "automation/hooks", + "automation/personal-swe-agent", "automation/cron-jobs", "automation/cron-vs-heartbeat", "automation/troubleshooting", diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md index 1a5e921c01d5..e0cfff7e9983 100644 --- a/docs/gateway/configuration.md +++ b/docs/gateway/configuration.md @@ -254,6 +254,19 @@ When validation fails: + + Start from a documented autonomous engineering preset with: + + - `agents.defaults.workspace` + - restricted shell, git, and network policy examples + - maintenance cron loops + - explicit branch, commit, and PR conventions + - failure handling and Telegram status reporting + + See [Personal SWE agent preset](/automation/personal-swe-agent). + + + Enable HTTP webhook endpoints on the Gateway: From f279494bd14f0438125fcdd62d389d49f564165f Mon Sep 17 00:00:00 2001 From: Gotley_Tool Date: Sun, 22 Feb 2026 21:54:01 +1030 Subject: [PATCH 2/2] docs: fix unsupported schema fields in personal-swe-agent preset Updated the agent configuration documentation to include hooks, scratchpad checklist, and cron maintenance jobs. --- docs/automation/personal-swe-agent.md | 180 ++++++++++---------------- 1 file changed, 66 insertions(+), 114 deletions(-) diff --git a/docs/automation/personal-swe-agent.md b/docs/automation/personal-swe-agent.md index 4881ad42972c..ad0992c6375e 100644 --- a/docs/automation/personal-swe-agent.md +++ b/docs/automation/personal-swe-agent.md @@ -28,7 +28,25 @@ Use it when you want one agent profile that can: agents: { defaults: { workspace: "~/code", - systemPrompt: ` + }, + }, + cron: { + enabled: true, + maxConcurrentRuns: 1, + }, +} +``` + +> **Note:** The fields above are the only keys validated by `AgentDefaultsSchema` and the `cron` schema. +> Policy rules (system prompt, hooks, scratchpad) and cron job definitions are configured separately +> as described in the sections below. + +## Agent system prompt (conceptual policy) + +Set your agent's behavioral policy by providing a system prompt through the gateway's agent +configuration interface. The following is an example policy you can adapt: + +```text You are my personal SWE agent for local repositories. Scope and safety: @@ -51,117 +69,51 @@ Failure handling: - Retry budget: at most 2 retries per failing command, with one short diagnosis step between retries. - Stop and ask user when blocked by missing credentials, ambiguous product decisions, destructive changes, or repeated test failures. - Telegram status must include: objective, attempted commands, first actionable error, files changed, and next request for user. - `, - hooks: { - beforeCommand: { - shell: [ - { - name: "workspace-allowlist", - match: "*", - denyIfCwdOutside: ["~/code", "~/scratch/review"], - message: "Command blocked. Run only inside approved repo roots.", - }, - { - name: "block-destructive-shell", - matchRegex: "(^|\\s)(rm\\s+-rf|sudo\\s+rm|git\\s+clean\\s+-fdx)(\\s|$)", - action: "deny", - message: "Destructive shell command blocked by preset policy.", - }, - { - name: "require-checks-before-commit", - matchRegex: "(^|\\s)git\\s+commit(\\s|$)", - requireRecentCommands: ["pnpm test", "pnpm build"], - within: "30m", - action: "deny", - message: "Run pnpm test and pnpm build successfully before commit.", - }, - ], - git: [ - { - name: "branch-name-policy", - on: "branch-create", - requireNameRegex: "^(feat|fix|chore|docs)\\/[a-z0-9._-]+$", - action: "deny", - message: "Branch must match feat|fix|chore|docs/.", - }, - { - name: "commit-subject-policy", - on: "commit-msg", - requireSubjectRegex: "^(feat|fix|chore|docs|refactor|test)(\\([a-z0-9._-]+\\))?: .+", - action: "deny", - message: "Commit subject must follow Conventional Commit style.", - }, - { - name: "block-history-rewrite", - on: "push", - denyArgs: ["--force", "--force-with-lease"], - action: "deny", - message: "Force push is disabled in this preset.", - }, - ], - network: [ - { - name: "allow-docs-and-metadata-only", - action: "allowlist", - hosts: ["docs.openclaw.ai", "registry.npmjs.org", "api.github.com", "github.com"], - message: "Network access restricted to approved documentation and metadata hosts.", - }, - ], - }, - }, - scratchpad: { - commitChecklist: [ - "Run pnpm test", - "Run pnpm build", - "Summarize changed files", - "Write a Conventional Commit message", - ], - pullRequestTemplate: { - requiredFields: ["Summary", "Changes", "Tests", "Risks", "Rollback", "Follow ups"], - }, - }, - }, - }, - - cron: { - enabled: true, - maxConcurrentRuns: 1, - jobs: [ - { - id: "maintenance-deps-audit", - schedule: { kind: "cron", expr: "0 9 * * 1", tz: "UTC" }, - sessionTarget: "isolated", - payload: { - kind: "agentTurn", - message: "Run dependency and lockfile health checks in approved repos and report only actionable issues.", - }, - delivery: { mode: "announce", channel: "telegram", to: "tg:my-self-chat" }, - }, - { - id: "maintenance-doc-link-check", - schedule: { kind: "cron", expr: "0 15 * * 3", tz: "UTC" }, - sessionTarget: "isolated", - payload: { - kind: "agentTurn", - message: "Run docs link checks and summarize broken links with exact file paths.", - }, - delivery: { mode: "announce", channel: "telegram", to: "tg:my-self-chat" }, - }, - { - id: "maintenance-pr-hygiene", - schedule: { kind: "cron", expr: "0 12 * * 5", tz: "UTC" }, - sessionTarget: "isolated", - payload: { - kind: "agentTurn", - message: "Review open branches for stale work and prepare next-step PR drafts with required sections.", - }, - delivery: { mode: "announce", channel: "telegram", to: "tg:my-self-chat" }, - }, - ], - }, -} ``` +## Hooks (conceptual policy) + +The following hook definitions describe the intended enforcement policy for this preset. +Refer to the [Hooks](/automation/hooks) documentation for the supported configuration format. + +**Shell hooks:** + +- `workspace-allowlist`: deny commands run outside `~/code` or `~/scratch/review`. +- `block-destructive-shell`: deny `rm -rf`, `sudo rm`, and `git clean -fdx`. +- `require-checks-before-commit`: deny `git commit` unless `pnpm test` and `pnpm build` succeeded within the last 30 minutes. + +**Git hooks:** + +- `branch-name-policy`: deny branch creation unless the name matches `^(feat|fix|chore|docs)/[a-z0-9._-]+$`. +- `commit-subject-policy`: deny commit unless the subject matches Conventional Commit style. +- `block-history-rewrite`: deny `git push --force` and `git push --force-with-lease`. + +**Network hooks:** + +- `allow-docs-and-metadata-only`: restrict outbound requests to `docs.openclaw.ai`, `registry.npmjs.org`, `api.github.com`, and `github.com`. + +## Scratchpad checklist (conceptual) + +Use a scratchpad or notes section to track these items before each commit: + +- Run `pnpm test` +- Run `pnpm build` +- Summarize changed files +- Write a Conventional Commit message + +For PRs, ensure the body includes: Summary, Changes, Tests, Risks, Rollback, and Follow ups. + +## Cron maintenance jobs (conceptual) + +The `cron` config key enables scheduled agent runs. The following jobs illustrate the intended +maintenance schedule. Refer to [Cron jobs](/automation/cron-jobs) for supported job configuration. + +| Job | Schedule | Task | +|-----|----------|------| +| `maintenance-deps-audit` | Every Monday 09:00 UTC | Dependency and lockfile health checks | +| `maintenance-doc-link-check` | Every Wednesday 15:00 UTC | Docs link checks, report broken links | +| `maintenance-pr-hygiene` | Every Friday 12:00 UTC | Review stale branches, prepare PR drafts | + ## Policy examples included in the preset ### Allowed repo roots and workspaces @@ -172,10 +124,10 @@ Failure handling: ### Preferred branch naming - Required branch name format: - - `feat/` - - `fix/` - - `chore/` - - `docs/` + - `feat/` + - `fix/` + - `chore/` + - `docs/` ### Commit message pattern