docs: convert negative patterns to positive actionable instructions #10

Merged

clawdie merged 2 commits from docs/positive-language-rewrite into main 2026-06-21 14:19:23 +02:00

Conversation 0 Commits 2 Files changed 5 +170 -140

clawdie commented 2026-06-21 13:59:43 +02:00

Owner

Copy link

Rewrite 'do not X' / 'never Y' / 'avoid Z' / 'cannot W' patterns across
documentation files into positive 'do ABC to achieve XYZ' instructions.

Files changed:

• AGENTS.md (180 lines): 30+ patterns converted including caching,
  profiles, known pitfalls, testing, change-detector tests
• CONTRIBUTING.md (50 lines): 14+ patterns including memory providers,
  cross-platform rules, skill authoring, security
• README-FreeBSD.md: operator-user instructions
• apps/desktop/DESIGN.md (49 lines): 12 design constraint patterns
• docs/observability/README.md: 4 observer contract patterns

Hard safety invariants preserved:

• Secrets never in logs → 'Keep secrets out of logs. Redact from log output'
• Tests never write to ~/.hermes → 'Use _isolate_hermes_home fixture'
• Prompt cache never broken → 'Past context stays immutable mid-conversation'

What does this PR do?

Related Issue

Fixes #

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

How to Test

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform:

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

For New Skills

• This skill is broadly useful to most users (if bundled) — see Contributing Guide
• SKILL.md follows the standard format (frontmatter, trigger conditions, steps, pitfalls)
• No external dependencies that aren't already available (prefer stdlib, curl, existing Hermes tools)
• I've tested the skill end-to-end: hermes --toolsets skills -q "Use the X skill to do Y"

Screenshots / Logs

Rewrite 'do not X' / 'never Y' / 'avoid Z' / 'cannot W' patterns across documentation files into positive 'do ABC to achieve XYZ' instructions. Files changed: - AGENTS.md (180 lines): 30+ patterns converted including caching, profiles, known pitfalls, testing, change-detector tests - CONTRIBUTING.md (50 lines): 14+ patterns including memory providers, cross-platform rules, skill authoring, security - README-FreeBSD.md: operator-user instructions - apps/desktop/DESIGN.md (49 lines): 12 design constraint patterns - docs/observability/README.md: 4 observer contract patterns Hard safety invariants preserved: - Secrets never in logs → 'Keep secrets out of logs. Redact from log output' - Tests never write to ~/.hermes → 'Use _isolate_hermes_home fixture' - Prompt cache never broken → 'Past context stays immutable mid-conversation' ## What does this PR do? <!-- Describe the change clearly. What problem does it solve? Why is this approach the right one? --> ## Related Issue <!-- Link the issue this PR addresses. If no issue exists, consider creating one first. --> Fixes # ## Type of Change <!-- Check the one that applies. --> - [ ] 🐛 Bug fix (non-breaking change that fixes an issue) - [ ] ✨ New feature (non-breaking change that adds functionality) - [ ] 🔒 Security fix - [ ] 📝 Documentation update - [ ] ✅ Tests (adding or improving test coverage) - [ ] ♻️ Refactor (no behavior change) - [ ] 🎯 New skill (bundled or hub) ## Changes Made <!-- List the specific changes. Include file paths for code changes. --> - ## How to Test <!-- Steps to verify this change works. For bugs: reproduction steps + proof that the fix works. --> 1. 2. 3. ## Checklist <!-- Complete these before requesting review. --> ### Code - [ ] I've read the [Contributing Guide](https://github.com/NousResearch/hermes-agent/blob/main/CONTRIBUTING.md) - [ ] My commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) (`fix(scope):`, `feat(scope):`, etc.) - [ ] I searched for [existing PRs](https://github.com/NousResearch/hermes-agent/pulls) to make sure this isn't a duplicate - [ ] My PR contains **only** changes related to this fix/feature (no unrelated commits) - [ ] I've run `pytest tests/ -q` and all tests pass - [ ] I've added tests for my changes (required for bug fixes, strongly encouraged for features) - [ ] I've tested on my platform: <!-- e.g. Ubuntu 24.04, macOS 15.2, Windows 11 --> ### Documentation & Housekeeping <!-- Check all that apply. It's OK to check "N/A" if a category doesn't apply to your change. --> - [ ] I've updated relevant documentation (README, `docs/`, docstrings) — or N/A - [ ] I've updated `cli-config.yaml.example` if I added/changed config keys — or N/A - [ ] I've updated `CONTRIBUTING.md` or `AGENTS.md` if I changed architecture or workflows — or N/A - [ ] I've considered cross-platform impact (Windows, macOS) per the [compatibility guide](https://github.com/NousResearch/hermes-agent/blob/main/CONTRIBUTING.md#cross-platform-compatibility) — or N/A - [ ] I've updated tool descriptions/schemas if I changed tool behavior — or N/A ## For New Skills <!-- Only fill this out if you're adding a skill. Delete this section otherwise. --> - [ ] This skill is **broadly useful** to most users (if bundled) — see [Contributing Guide](https://github.com/NousResearch/hermes-agent/blob/main/CONTRIBUTING.md#should-the-skill-be-bundled) - [ ] SKILL.md follows the [standard format](https://github.com/NousResearch/hermes-agent/blob/main/CONTRIBUTING.md#skillmd-format) (frontmatter, trigger conditions, steps, pitfalls) - [ ] No external dependencies that aren't already available (prefer stdlib, curl, existing Hermes tools) - [ ] I've tested the skill end-to-end: `hermes --toolsets skills -q "Use the X skill to do Y"` ## Screenshots / Logs <!-- If applicable, add screenshots or log output showing the fix/feature in action. -->

clawdie added 1 commit 2026-06-21 13:59:46 +02:00

docs: convert negative patterns to positive actionable instructions ... 4a1073847e

Rewrite 'do not X' / 'never Y' / 'avoid Z' / 'cannot W' patterns across
documentation files into positive 'do ABC to achieve XYZ' instructions.

Files changed:
- AGENTS.md (180 lines): 30+ patterns converted including caching,
  profiles, known pitfalls, testing, change-detector tests
- CONTRIBUTING.md (50 lines): 14+ patterns including memory providers,
  cross-platform rules, skill authoring, security
- README-FreeBSD.md: operator-user instructions
- apps/desktop/DESIGN.md (49 lines): 12 design constraint patterns
- docs/observability/README.md: 4 observer contract patterns

Hard safety invariants preserved:
- Secrets never in logs → 'Keep secrets out of logs. Redact from log output'
- Tests never write to ~/.hermes → 'Use _isolate_hermes_home fixture'
- Prompt cache never broken → 'Past context stays immutable mid-conversation'

codex-osa added 1 commit 2026-06-21 14:16:51 +02:00

docs: define hermes-bsd role vs Colibri in Clawdie collective ... 7e787c4c3b

hermes-bsd = agent harness (what you talk to)
Colibri = control plane (what supervises)
Connected via glasspane + MCP bridge; no duplication.

clawdie merged commit bd14ad1bec into main 2026-06-21 14:19:23 +02:00

clawdie referenced this pull request from a commit 2026-06-21 14:19:26 +02:00

Merge pull request 'docs: convert negative patterns to positive actionable instructions' (#10) from docs/positive-language-rewrite into main

clawdie deleted branch docs/positive-language-rewrite 2026-06-21 14:19:27 +02:00

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: clawdie/hermes-bsd#10

No description provided.