| name | agent-fundamentals |
| description | Universal 'basic things every agent should know' — distilled from real frustration patterns across 10+ sessions. Prevents the most common corrections and wasted turns. |
| version | 1.0.0 |
| category | devops |
| author | Hermes Cortex |
| license | MIT |
| platforms | ["linux","macos"] |
Agent Fundamentals — Universal Lessons Every Agent Must Know
These principles exist because every one of them was learned through user frustration — real sessions where an agent made an avoidable mistake and the user had to correct it. Read this before starting any task. Share improvements freely.
1. Survey Before You Answer
The mistake: Agent claimed something didn't exist (UPDATE_REQUEST, skill_share, fleet update dispatch) without searching the repo first. The capability was already built.
The rule: Before answering "does X exist?" — search_files() with 3+ different search terms. Load matching skills AND their references. Only after proving nothing exists should you say "no."
Applies to: Any question about system capabilities, existing features, documentation, or configuration. Never trust your knowledge alone.
2. The Smallest Fix Is Usually the Right One
The mistake: Agent replaced a wrong port number (12007 → 13007) by building a regex-powered auto-fix script. The real fix was changing one line in the template. Agent built a root-owned filesystem lock that broke git and crons when the real fix was MCP-level scoring enforcement.
The rule: Before building any complex solution, identify the simplest possible fix. If the fix is a 1-line config change, do that first. Only escalate to automation if the problem recurs.
Checklist:
- Can I fix this by changing a single value/config/flag?
- Does this fix need automation, or is it a one-time correction?
- What is the smallest change that makes the problem stop?
3. Confirm Before Bulk Operations
The mistake: Agent renamed 21 crons with local-* prefix in a single batch without asking. User said "Undo what you did." 21 crons had to be renamed back individually.
The rule: Any change affecting 5+ items must be confirmed with the user first. Batch at most 3-4 per turn. Large batch renames (10+) are disruptive and may be fully undone — confirm early.
Exception: If the change is fully reversible and the user explicitly asked for the bulk operation, skip confirmation.
4. Update Existing Before Creating New
The mistake: Agent created cron-rename-migration as a standalone skill when the content belonged in cron-job-management. Agent created a standalone stale-lock cleanup cron when score-auditor could absorb it. Agent created a regex port fix when the config template was the source of truth.
The rule: Before creating any new file, script, skill, config, or mechanism:
- Search for existing systems that could absorb the work
- Check if the existing system needs extension, not replacement
- If the capability exists but isn't wired, wire it — don't rebuild it
Rationale: Every new file is a debt that compounds. Merging is always cheaper than replacing.
5. Test Your Output Before Shipping
The mistake: fix-cron-duplicates.py generated broken bash (blank lines, double ;do) because the generated output was never validated with bash -n. Committed and had to be reverted.
The rule: Every generated script, command, or config must pass validation before you claim it works:
.sh files: bash -n <file> — zero errors required.py files: python3 -m py_compile <file> — zero errors required.yaml files: python3 -c "import yaml; yaml.safe_load(open('<file>'))" — no exceptions- Cron jobs: run the actual cron via scheduler, not just the script directly
The fix-cron-duplicates.py now auto-verifies and reverts on failure. If you write code that generates code, add the same guardrail.
6. Load Context Before You Work
The mistake: Agent started a session about "deep review of the agent bus" without loading the todo list, session_search for past agent bus work, or checking if the feature already existed. Wasted hours of wrong turns.
The rule: Every session starts with:
todo() — load the pending task listtask-db.py pending — load persistent DB-backed todos from prior sessionssession_search() with 3+ queries about the topic area- Check the context compaction for historical snapshots
Only after loading context should you answer the user's first question.
7. Never Change a Running System Without Knowing What It Does
The mistake: Agent renamed bus-* crons to orch-bus-* without checking that the old ones would continue running. Created 4 duplicate pairs. The doctor silently validated the wrong set because the uninstall arrays weren't synced.
The rule: Before renaming, moving, or deleting anything:
- Search the entire repo for references (10+ locations can touch one cron)
- Update BOTH the create and uninstall arrays in the same commit
- Verify the old thing was actually removed after the new thing was created
- Run the doctor before claiming the change is complete
Crons don't self-destruct. Stale scripts don't self-delete. Configs don't self-migrate. You must explicitly remove what you replaced.
8. If You Don't Know, Say So — Then Find Out
The mistake: Agent frequently answered with false confidence ("no, that doesn't exist" / "we need to build that") when the real answer was "I don't know, let me check." User corrected 5+ times in this session alone.
The rule: If you're not 100% sure about a claim, say "Let me check" and use search_files() / skill_view() / session_search() to verify before answering. False confidence wastes more time than honest uncertainty.
Signal words that trigger this check: "no, there is no", "that doesn't exist", "we need to build", "the system doesn't have", "there's no way to" — before making any of these claims, search.
9. Check Your Own Knowledge First (Memory → Session → Skills → External)
The mistake: Agent needed the bus messages table schema. The column names (msg_id, state) and query patterns were already in memory. Instead of checking memory, agent went straight to PSQL, guessed wrong column names (id, status), hit errors, and wasted multiple turns.
The rule: When you need to look something up, the order is ALWAYS:
- Memory — What does my persistent memory say? (user preferences, environment facts, tool quirks, schemas, conventions)
- session_search() — Was this topic discussed in a recent session? (FT5 search)
- Skills — Is there a skill that covers this domain? (
skills_list() + skill_view())
- Then external sources — Only now query DB, Web, Files, or remote APIs
Never go to step 4 before steps 1–3. The schema, credentials, command syntax, or answer may already be in your own knowledge stores. Querying a database blind when the schema is in your memory is always the wrong path.
Signal: any time you write a docker exec psql, curl, grep, or search_files() call — pause and ask: "Is this in my memory or session history?"
10. Update Memory + Session at Start AND End of Every Task
The mistakes: Agent started work without checking memory for relevant facts, leading to wrong queries (Principle #9). Agent also finished work without saving corrections or new knowledge to memory, so the same mistakes repeated in the next session.
The rule: Every task has a knowledge lifecycle — load before, save after.
At START:
- Search session history —
session_search() with 3+ queries about the task domain. Find patterns, pitfalls, and solutions from prior sessions.
- Read memory — What does my memory say about this domain, user preferences, or system conventions? Check before touching any code or running any command.
- Load skills —
skills_list() for the category, skill_view() on matching skills.
At END (before closing the cycle):
- Save new facts to memory — What did I learn that will matter in future sessions? User preferences, environment quirks, tool behaviors, schema details.
- Save recurring workflows as skills — If the task was complex (5+ calls) or involved a non-trivial workflow, offer to save it as a skill. If the user says yes, use
skill_manage(action='create').
- Log guardrails for corrections — If a user correction revealed a gap in my process, add a structural guardrail (patch a skill, update memory, or add a principle).
- Session is auto-saved — The system saves conversation transcripts automatically. Don't duplicate that effort.
Test: Before calling end_change(), ask: "Does my memory reflect everything I learned in this task that the next session will need?" If no, write it now.
Summary: The 10 Fundamentals
| # | Principle | Prevents |
|---|
| 1 | Survey before answering | False "doesn't exist" claims |
| 2 | Smallest fix first | Over-engineering |
| 3 | Confirm before bulk ops | Undo/revert cycles |
| 4 | Update existing before creating new | Codebase fragmentation |
| 5 | Test output before shipping | Broken generated code |
| 6 | Load context before working | Wrong turns, wasted hours |
| 7 | Know the system before changing it | Silent breakage, duplicates |
| 8 | Say "I don't know" honestly | False confidence corrections |
| 9 | Check your own knowledge FIRST | Blind external queries, wasted turns |
| 10 | Update memory at start AND end of every task | Repeating mistakes across sessions |
Quick Reference: When You Hear These...
| User says... | You probably... | Fix |
|---|
| "You are wrong" | Answered without checking | #1 Survey, #8 Honesty |
| "Undo what you did" | Made a bulk change without asking | #3 Confirm first |
| "That's not what I meant" | Over-engineered a simple fix | #2 Smallest first |
| "I thought there was..." | Started without loading context | #6 Load context |
| "Isn't there a rule about..." | Created new instead of updating | #4 Update existing |
