|
| 1 | +# AGENTS.md - Workspace Rules |
| 2 | + |
| 3 | +## Memory Owner |
| 4 | + |
| 5 | +The configured memory owner is **OpenClaw**. Side harnesses may keep local session context, but durable knowledge must be written as a Memory Handoff in `.claude/memory-handoffs/`. The memory owner ingests those handoffs into canonical durable memory. |
| 6 | + |
| 7 | +Do not create a second canonical memory system. If a session produced durable knowledge, write the handoff and let the owner route it. |
| 8 | + |
| 9 | +## Every Session |
| 10 | + |
| 11 | +- Read the repo-local instructions before editing. |
| 12 | +- Prefer root-cause fixes over surface patches. |
| 13 | +- Run the smallest meaningful verification before claiming success. |
| 14 | +- Ask before destructive, production-impacting, or dependency-adding work. |
| 15 | + |
| 16 | +## Memory Handoff |
| 17 | + |
| 18 | +If a session discovers durable knowledge - architecture decisions, workflow changes, non-obvious fixes, setup gotchas, security findings, reusable commands, durable research, or user preferences - create a handoff at the end of the task. |
| 19 | + |
| 20 | +Write the handoff to `.claude/memory-handoffs/<YYYY-MM-DD-HHMM>-<slug>.md` using the format in `.claude/memory-handoffs/TEMPLATE.md`. |
| 21 | + |
| 22 | +Do not wait to be reminded. Do not edit canonical memory directly unless this is the memory owner. |
| 23 | + |
| 24 | +## Safety |
| 25 | + |
| 26 | +- Never expose secrets, private hostnames, account IDs, or internal endpoints in public output. |
| 27 | +- Use deterministic scrubbers before publishing generated content. |
| 28 | +- Do not bypass security checks unless the user explicitly accepts the risk. |
| 29 | +- Read `SAFETY_RULES.md` for hard boundaries. |
| 30 | + |
| 31 | +## Multi-Agent Workflow |
| 32 | + |
| 33 | +- Delegate bounded tasks with clear ownership. |
| 34 | +- Keep write scopes separate when multiple agents work in parallel. |
| 35 | +- Integrate results before reporting completion. |
| 36 | + |
| 37 | +## Solo-mise repo-specific rules |
| 38 | + |
| 39 | +This is the source repo for `solo-mise` itself. The files here are templates that get installed into *other* directories, so the bar for safety is higher than usual. |
| 40 | + |
| 41 | +### Before committing |
| 42 | + |
| 43 | +- `python -m pytest -q` must pass (currently 40 tests). |
| 44 | +- `PYTHONPATH=$HOME/repos/content-guard/src python -m content_guard scan . --policy $HOME/repos/content-guard/policies/public-repo.json` must report `Clean.` or warn-only. |
| 45 | +- New profile JSON entries must use relative paths only - no absolute paths, no `..` segments. The path validator in `src/solo_mise/init.py:_ensure_safe_rel` enforces this at runtime; tests cover it in `tests/test_init.py::test_init_rejects_unsafe_profile_paths`. |
| 46 | + |
| 47 | +### Invariants worth not breaking |
| 48 | + |
| 49 | +- **Ingester `promote_cards` and `route_documents` default to `False`.** They are opt-in. Codex flagged the original "default on" as a BLOCKER for a public-safety installer. If you find yourself flipping these, write a memory handoff explaining why first. |
| 50 | +- **`init` refuses `$HOME` as target unless `--allow-home`.** Don't relax this without an alternative guard. |
| 51 | +- **`init --dry-run` does not mkdir.** Verified by `test_dry_run_creates_no_files_or_dirs`. |
| 52 | +- **Inboxed handoffs are copied verbatim, not reconstructed.** Reviewers need to see what the harness actually wrote. |
| 53 | + |
| 54 | +### Template hygiene |
| 55 | + |
| 56 | +- Every text template under `src/solo_mise/templates/` gets `{{placeholder}}` substitution. Keep placeholders bounded to: `memory_owner`, `memory_owner_name`, `profile`, `harness`. New placeholders require a corresponding entry in `init.py::context`. |
| 57 | +- Templates must pass content-guard's `public-repo` policy. The repo's own pre-push hook scans them. Inline allow tags (`<!-- content-guard: allow <rule-id> -->`) are okay for documented examples; bulk-disabling rules is not. |
| 58 | + |
| 59 | +### Releases |
| 60 | + |
| 61 | +See `RELEASE.md` for the checklist. Tag, push, verify pipx install from tag. |
| 62 | + |
| 63 | +### OpenClaw integration |
| 64 | + |
| 65 | +This repo is dogfooded with `--profile openclaw`. The fragments under `.solo-mise/openclaw/` are placeholders - if you actually wire this repo into a live OpenClaw workspace, edit them with real provider/model ids before merging into `~/.openclaw/openclaw.json`. The fragments use `<provider/main-model-id>` style sentinels that will fail the gateway if merged unedited. |
0 commit comments