From 615ea2f1a4881f0cca4917567a929c9744a2db1e Mon Sep 17 00:00:00 2001 From: techartdev Date: Wed, 25 Feb 2026 18:13:45 +0200 Subject: [PATCH] agentic instructions and guidelines --- .github/instructions/copilot.instructions.md | 56 ++++++++++ .vscode/extensions.json | 9 ++ .vscode/settings.json | 44 ++++++++ AGENTS.md | 108 +++++++++++++++++++ CLAUDE.md | 1 + 5 files changed, 218 insertions(+) create mode 100644 .github/instructions/copilot.instructions.md create mode 100644 .vscode/extensions.json create mode 100644 .vscode/settings.json create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/.github/instructions/copilot.instructions.md b/.github/instructions/copilot.instructions.md new file mode 100644 index 0000000..9d82068 --- /dev/null +++ b/.github/instructions/copilot.instructions.md @@ -0,0 +1,56 @@ +# OpenClaw Home Assistant Add-on Patterns + +Always reuse existing logic in `run.sh`, `oc_config_helper.py`, and `render_nginx.py`. +Avoid duplicate implementations for config parsing, gateway patching, or template rendering. +Respect guidelines in AGENTS.md + +## Stack + +- Home Assistant add-on (Debian Bookworm base) +- Bash runtime orchestrator (`run.sh`) +- Python helper scripts for config/template work +- nginx template rendering +- YAML config schema + 6 locale translation files + +## Source of Truth + +- Add-on options/schema: `openclaw_assistant_dev/config.yaml` +- Runtime boot logic: `openclaw_assistant_dev/run.sh` +- Safe OpenClaw config edits: `openclaw_assistant_dev/oc_config_helper.py` +- nginx + landing rendering: `openclaw_assistant_dev/render_nginx.py` +- UI text in Home Assistant: `openclaw_assistant_dev/translations/*.yaml` +- User-facing docs: `DOCS.md` + +## Required Sync Rules + +When changing add-on options, update in the same PR: + +1. `config.yaml` option default + schema +2. All translation files (`en`, `bg`, `de`, `es`, `pl`, `pt-BR`) +3. `DOCS.md` config/troubleshooting sections +4. `CHANGELOG.md` + +When changing landing/nginx placeholders: +- Keep template keys and `render_nginx.py` replacements in sync. + +## Security Rules + +- Do not log secrets/tokens. +- For gateway token docs/UI guidance, do not use `openclaw config get gateway.auth.token` (redacted in v2026.2.22+). +- Prefer `jq -r '.gateway.auth.token' /config/.openclaw/openclaw.json`. + +## Editing Rules + +- Keep fixes minimal and root-cause focused. +- Preserve backward compatibility for existing add-on options unless migration is explicit. +- Do not change unrelated behavior while fixing one issue. + +## Validation Commands + +```sh +bash -n openclaw_assistant_dev/run.sh +python3 -m py_compile openclaw_assistant_dev/oc_config_helper.py +python3 -m py_compile openclaw_assistant_dev/render_nginx.py +``` + +If behavior changes are user-visible, update `openclaw_assistant_dev/CHANGELOG.md`. diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..7646d83 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,9 @@ +{ + "recommendations": [ + "timonwong.shellcheck", + "redhat.vscode-yaml", + "ms-python.python", + "ms-python.vscode-pylance", + "esbenp.prettier-vscode" + ] +} diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..667aafc --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,44 @@ +{ + "editor.formatOnSave": true, + "files.insertFinalNewline": true, + "files.trimFinalNewlines": true, + "files.eol": "\n", + + "[shellscript]": { + "editor.tabSize": 2, + "editor.insertSpaces": true + }, + "[yaml]": { + "editor.tabSize": 2, + "editor.insertSpaces": true + }, + "[python]": { + "editor.tabSize": 4, + "editor.insertSpaces": true + }, + "[markdown]": { + "editor.wordWrap": "on", + "editor.quickSuggestions": { + "comments": "off", + "strings": "off", + "other": "off" + } + }, + + "files.associations": { + "*.tpl": "nginx" + }, + + "yaml.validate": true, + "yaml.format.enable": true, + + "shellcheck.enable": true, + "shellcheck.run": "onType", + + "python.analysis.typeCheckingMode": "basic", + "python.analysis.autoImportCompletions": true, + + "search.exclude": { + "**/__pycache__": true + } +} diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..1771057 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,108 @@ +# Repository Guidelines + +## Project Scope + +This repository builds the **OpenClaw Assistant (DEV)** Home Assistant add-on. +The add-on packages OpenClaw + nginx + ttyd and manages startup/configuration glue. + +## Architecture at a Glance + +- Add-on root metadata/docs: + - `README.md` + - `DOCS.md` + - `SECURITY.md` + - `repository.yaml` +- Runtime implementation (all add-on behavior lives here): + - `openclaw_assistant_dev/run.sh` (PID 1 orchestrator) + - `openclaw_assistant_dev/oc_config_helper.py` (safe JSON config edits) + - `openclaw_assistant_dev/render_nginx.py` (template rendering) + - `openclaw_assistant_dev/nginx.conf.tpl` + - `openclaw_assistant_dev/landing.html.tpl` + - `openclaw_assistant_dev/config.yaml` (HA options + schema) + - `openclaw_assistant_dev/translations/*.yaml` (all locale UI strings) + - `openclaw_assistant_dev/Dockerfile` + - `openclaw_assistant_dev/CHANGELOG.md` + +## Core Rules + +- Fix root causes, not symptoms. +- Keep edits surgical; do not refactor unrelated code. +- Never introduce insecure defaults. +- Never log secrets or auth tokens. +- Keep behavior backward-compatible unless the change explicitly requires a migration. + +## Add-on Config Coupling Rules (Critical) + +When adding/changing any add-on option, update **all** of the following in one change: + +1. `openclaw_assistant_dev/config.yaml` + - `options:` default + - `schema:` validation entry + - comments/help text +2. `openclaw_assistant_dev/translations/en.yaml` +3. `openclaw_assistant_dev/translations/bg.yaml` +4. `openclaw_assistant_dev/translations/de.yaml` +5. `openclaw_assistant_dev/translations/es.yaml` +6. `openclaw_assistant_dev/translations/pl.yaml` +7. `openclaw_assistant_dev/translations/pt-BR.yaml` +8. `DOCS.md` configuration reference / troubleshooting if user-facing +9. `openclaw_assistant_dev/CHANGELOG.md` + +If any of these are skipped, the UX becomes inconsistent in HA. + +## Runtime Safety Rules + +- `run.sh` runs with `set -euo pipefail`; avoid constructs that fail unexpectedly under `set -e`. +- Validate all user-provided values from `/data/options.json` before injecting into shell/nginx/openclaw config. +- Keep `run.sh` idempotent on restart (multiple starts must not corrupt state). +- Treat `/config/` as persistent state; never wipe user data unless explicitly requested. + +## Gateway/Auth/Security Rules + +- OpenClaw v2026.2.22+ redacts sensitive values in `openclaw config get`. + - For token retrieval guidance, prefer: `jq -r '.gateway.auth.token' /config/.openclaw/openclaw.json`. +- `trusted-proxy` mode may reject direct local CLI WS calls (`trusted_proxy_user_missing`); document this clearly instead of hiding it. +- For `lan_https` certificate logic, keep SAN generation deterministic and regeneration-triggered on SAN/IP changes. + +## Template Coupling Rules + +- If adding placeholders in `landing.html.tpl` or `nginx.conf.tpl`, update `render_nginx.py` in the same change. +- If landing-page guidance changes (commands/errors), sync corresponding troubleshooting text in `DOCS.md`. + +## Versioning and Changelog + +- User-visible changes should update: + - `openclaw_assistant_dev/CHANGELOG.md` + - `openclaw_assistant_dev/config.yaml` version +- Keep changelog entries user-facing and action-oriented. + +## Coding Style + +- Shell: POSIX-friendly Bash, explicit quoting, descriptive variable names. +- Python: small focused helpers, explicit error handling, no hidden side effects. +- YAML/Markdown: preserve existing style and structure. +- Avoid adding dependencies unless necessary. + +## Validation Checklist (Run After Relevant Changes) + +From repo root: + +```sh +bash -n openclaw_assistant_dev/run.sh +python3 -m py_compile openclaw_assistant_dev/oc_config_helper.py +python3 -m py_compile openclaw_assistant_dev/render_nginx.py +``` + +For option changes: +- verify `config.yaml` option + schema + all translations exist +- verify `DOCS.md` matches current behavior + +For startup/auth/proxy/cert changes: +- verify log messages remain clear and actionable +- verify `landing.html.tpl` instructions match actual commands + +## Commit Scope + +- Group related changes only. +- Do not include unrelated formatting churn. +- Do not edit generated/cache folders (`__pycache__`, temporary outputs). diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..c317064 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md