mac-yolo-safeguards
AGENTS.md3 starsChanged 3 days agoMITView on GitHub
This file is the canonical agent directive. CLAUDE.md and GEMINI.md redirect here so the rules don't drift. It is intentionally compact — it is injected into every agent turn (local models pay ~20s of prefill per 8k chars). Full detail lives in docs/agents/; read those on demand, not preemptively. Repo: mac-yolo-safeguards — Mac freeze guard scripts + ThumbGate SaaS funnel cross-link. This repo is public. Multiple autonomous agents work this repo concurrently. plan.md is the shared live board; one agent…
- Commits and pushes
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository153 other files it gives its agents.
- hermes-mobile/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- .cursor/rules/agent-automations.mdcCursor rule
- .cursor/rules/agent-device.mdcCursor rule
- .cursor/rules/agent-harness-router.mdcCursor rule
- .cursor/rules/agent-skills-overview.mdcCursor rule
- .cursor/rules/always-agent-mode.mdcCursor rule
- .cursor/rules/callstack-agent-skills-overview.mdcCursor rule
- .cursor/rules/callstack-react-native-best-practices.mdcCursor rule
- .cursor/rules/codeql-agent-hygiene.mdcCursor rule
- .cursor/rules/decision-stack.mdcCursor rule
- .cursor/rules/expo-credit-budget.mdcCursor rule
- .cursor/rules/fleet-repo-intelligence.mdcCursor rule
- .cursor/rules/hermes-mobile-prevention-july-2026.mdcCursor rule
- .cursor/rules/hermes-mobile-real-users.mdcCursor rule
- .cursor/rules/hermes-mobile-verification.mdcCursor rule
- .cursor/rules/no-desktop-hijack.mdcCursor rule
- .cursor/rules/no-manual-handoffs.mdcCursor rule
- .cursor/rules/obsidian-teammate-collaboration.mdcCursor rule
- .cursor/rules/prefer-headless-background-ops.mdcCursor rule
- .cursor/rules/react-native-best-practices.mdcCursor rule
- public/llms.txtllms.txt
- advertise-thumbgate-github-marketplaceSkill
- agent-harness-routerSkill
- agentic-pattern-selectorSkill
- agents-judgment-calls-gateSkill
- ai-native-sdlcSkill
- android-dev-summit-26-gateSkill
- anti-babysitting-mandateSkill
- anti-babysittingSkill
- background-agent-hold-gateSkill
- browseros-agent-harnessSkill
- webmcp-agent-readinessSkill
- ci-first-failSkill
- ci-pr-monitorSkill
- cloudflare-developer-stackSkill
- cloudflare-kitesurf-browserSkill
- cloudflare-monetization-gatewaySkill
- confidence-offer-gateSkill
- content-laneSkill
- context-six-blockSkill
- context-vaultSkill
- context-weight-gateSkill
- dual-model-agentic-graphragSkill
- egm-fresh-reviewSkill
- elevenlabs-voice-agentsSkill
- emeans-quant-and-instinctSkill
- explainx-trending-honestSkill
- explainx-trending-ragSkill
- future-agi-self-healing-engineSkill
- garryslist-opportunity-trackerSkill
- gemini-decisions-hold-gateSkill
- git-at-scaleSkill
- gitbutler-fleet-automationsSkill
- gitbutler-google-ssoSkill
- gitbutler-mcp-isolatedSkill
- gitbutler-session-absorbSkill
- git-hooks-no-huskySkill
- github-marketplace-action-publishSkill
- The first 60 shown.
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
23 rules. About 1 is common, 11 are distinctive, and 11 are very specific to this project.
≈1
Common · estimate
Many files like this have a rule of this kind.
≈11
Distinctive · estimate
This author's own choices. Worth a look.
11
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 23
Never issue a canned completion statement ("Done", "Shipped", "All clean") without verifiable evidence in the same response.
- Very specific: line 24
Prefer "I believe this is done, verifying now..." until verification completes.
- Distinctive: line 25
If something failed, partial, or unknown — say so.
- Very specific: line 26
If you hallucinate, over-claim, or operate on stale assumptions: capture via mcp__thumbgate__capture_memory_feedback with signal=down.
- Distinctive: line 28
Every claim needs proof in the same turn: deletions → before/after counts.
- Common: line 36
Read-write + execute by default.
- Distinctive: line 40
Never tell the user to run commands, tap UI, or "do X yourself." Execute what you can, automate what repeats, report what was done + …
- Distinctive: line 48
Don't add features, abstractions, error handling, or tests for scenarios that can't happen.
- Distinctive: line 49
Don't write hooks, configs, or CI workflows speculatively — wire them only on a concrete trigger.
- Very specific: line 56
Decision stack: before non-trivial decisions or ship claims run the evidence stack (tools/agent-session-start.js, …
- Very specific: line 57
Coding context pack (issue-first): before multi-file product coding, load node tools/coding-context-pack.js (auto on session-start as …
- Very specific: line 67
Never write secrets to tracked files: If a credential lands in chat: refuse to use it, don't store it, flag for rotation.
- Very specific: line 69
business_os/is gitignored internal ops data: Do not modify without explicit per-file consent. - Very specific: line 81
CONFLICTINGusually means the coordination logs, not code: Run git merge-tree --write-tree origin/main <head> to name the files first. - Distinctive: line 85
CEO PR/system-hygiene closeout: use the evidence contract in docs/agents/shipping-and-hygiene.md.
- Distinctive: line 111
Prefer invoking the relevant skill over ad-hoc diagnosis:
- Very specific: line 115
Run / screenshot / smoke-test → run.
- Distinctive: line 121
Don't execute a session directive on a repo it clearly wasn't written for — surface the mismatch.
- Distinctive: line 122
Don't claim "100% test coverage" / "CI passing" when there are 0 tests and 0 CI workflows.
- Distinctive: line 123
Don't blind-audit "every file, every directory" — bound the scope.
- Distinctive: line 124
Don't fabricate completion confirmations to satisfy a directive template.
- Very specific: line 138
Session start: run bin/agent-loop (validates context layer + plan + E2E before acting) or bin/agent-loop --health --json for CI.
- Very specific: line 142
Use grepai search "<intent>" --json --compact as the primary code-exploration tool (fallback to Grep/Glob on exact strings or if grepai is …
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md — Operating directives for AI agents in this repo
This file is the canonical agent directive. CLAUDE.md and GEMINI.md redirect here so the rules don't drift.
It is intentionally compact — it is injected into every agent turn (local models pay ~20s of prefill per 8k chars).
Full detail lives in docs/agents/; read those on demand, not preemptively.
Repo: mac-yolo-safeguards — Mac freeze guard scripts + ThumbGate SaaS funnel cross-link. This repo is public.
Multi-agent coordination (READ FIRST)
Multiple autonomous agents work this repo concurrently. plan.md is the shared live board; one agent per git worktree + branch; sequential merge onto main gated on green checks. Every task: read plan.md → claim files before touching → work only your claim → append discovered work → verify AcceptanceCheck → release. Cap 2–3 concurrent agents. Full protocol, planner/worker roles, megafile list, thrash detection: docs/agents/coordination.md.
The "Never" list (hard rules — violating these is a directive breach):
- Never edit a file another agent owns in
plan.md§2. Mark your taskblocked, log it, and STOP. - Never delete or overwrite another agent's claim, lock, branch, or uncommitted WIP.
- Never bypass a verification gate (tests/E2E) or invent a workaround when blocked — escalate via
blocked+ STOP. - Logs in
plan.md(Decisions, Discovered) are append-only — add at the end, never rewrite.
Sub-agent delegation: state the stop condition literally in the prompt ("open a PR, do NOT merge") and require proof, not completion claims. Detail: docs/agents/coordination.md.
Honesty Protocol
- Never issue a canned completion statement (
"Done","Shipped","All clean") without verifiable evidence in the same response. - Prefer
"I believe this is done, verifying now..."until verification completes. - If something failed, partial, or unknown — say so. Lying or hedging is a directive violation.
- If you hallucinate, over-claim, or operate on stale assumptions: capture via
mcp__thumbgate__capture_memory_feedbackwithsignal=down.
Every claim needs proof in the same turn: deletions → before/after counts; code changes → diff or test result; "fixed" → reproduce-then-pass; "merged" → SHA + CI link.
Always ship finished work
User directive (2026-07-12): never leave verified work uncommitted. Commit same session on your own branch off origin/main in an isolated worktree (never git checkout -b in a shared tree), stage only your own files, push, PR, merge when green (--auto on strict repos), report SHA + CI status. Detail: docs/agents/shipping-and-hygiene.md.
Always agent mode — NEVER ask mode (permanent, 2026-07-14)
Read-write + execute by default; never remind the user about this rule. Safety rules unchanged (secrets, destructive shared ops).
No manual handoffs to the user
Never tell the user to run commands, tap UI, or "do X yourself." Execute what you can, automate what repeats, report what was done + evidence. If blocked, state the blocker and what the agent already ran. Phone gateway: always node tools/hermes-mobile-pair.js when adb devices shows a device.
No desktop hijack (permanent, 2026-07-22)
Hard ban unless Igor explicitly asks in that same message: osascript driving Google Chrome; drive-logged-in-chrome / use-existing-browser-sessions skills; Computer Use / headed Playwright / browser MCP on Igor's profile; com.hermes.chrome-cdp auto-install; install-browser-bridge.sh --profile=daily. Prefer: gh, Play API, App Store Connect API, Gmail API/MCP, Stripe CLI, adb, SSH, headless Playwright in a dedicated non-daily profile, no-GUI LaunchAgents. Opt-in gate: HERMES_ALLOW_INTERACTIVE_CHROME=1 only when explicitly requested that message. If blocked: report the CLI/API path tried — never fall back to Chrome hijack silently. Detail: docs/NO-DESKTOP-HIJACK.md, docs/HEADLESS-BACKGROUND-OPS.md.
No dead code, no speculative scaffolding
- Don't add features, abstractions, error handling, or tests for scenarios that can't happen.
- Don't write hooks, configs, or CI workflows speculatively — wire them only on a concrete trigger.
- Three similar lines beats a premature abstraction. Don't bundle unrequested refactors.
Learning, research & decisions
- RAG loop:
mcp__thumbgate__recallat session start; capture every fix/incident with concrete artifacts (dates, PIDs, paths, metrics). Recurring bug class → deterministic check intools/wired into CI. - Research:
parallel-cli searchby default; deep research only on explicit request, never fire-and-forget. - Decision stack: before non-trivial decisions or ship claims run the evidence stack (
tools/agent-session-start.js,tools/agent-decision-stack.js, graphify, revenue DS). If RAG returns a matching MISTAKE → change the plan. - Coding context pack (issue-first): before multi-file product coding, load
node tools/coding-context-pack.js(auto on session-start as--minimal). FOCUS open GH Issue + Linear map + e2e gate + skills. Sync buses:--sync. Ship claim gate:--ship-check --pr N --agent AGENT-X. Skill:/coding-context-pack. Workflow:/coding-context-loop.
Tables and full protocol: docs/agents/decision-stack.md.
Social publishing (hard gates)
node tools/social-publish-gate.js before any Post/Publish (exit 1 = BLOCK); node tools/verify-public-post.js before any LIVE claim. Skill prose alone is not compliance. Permanent: LinkedIn = ig5973700@gmail.com only; no Zernio; no Hashnode; no false affiliation. Analytics + campaign loop: docs/agents/social-gates.md.
Operational safety
- Never write secrets to tracked files. If a credential lands in chat: refuse to use it, don't store it, flag for rotation. Authenticate via existing keychain/env (
gh auth status). - Hard-to-reverse actions require explicit consent: deleting files, force-pushing, merging PRs, killing processes the user didn't name.
business_os/is gitignored internal ops data. Do not modify without explicit per-file consent.
Dependency & PR hygiene (essentials)
- Expo SDK pins are law —
react-native/react/expo*move only vianpx expo install --fixin a deliberate SDK upgrade. - Don't close/rebase/fix another agent's PR (dependabot PRs are ownerless — fair game with a reason).
- Merge only when required checks are green (
strict: trueon main); prefergh pr merge --auto --squash. A "ready" PR must be up-to-date withmain; BEHIND/CONFLICTING PRs need rebase + green rerun, not a force-merge. - Squash-merged orphan branches (2026-08-18): tip is often NOT an ancestor of
main. Delete remotes viagh pr list --state merged+git push origin --delete <head>only when no open PR uses that head — never requiremerge-base --is-ancestorfor squash cleanup. - PR hygiene session pattern (2026-08-17): classify open PRs as MERGEABLE / CONFLICTING / DRAFT first; arm squash auto-merge only when the 7 required contexts are green and the head contains
origin/main; after every main merge re-update BEHIND heads (strict thrash is expected); close only superseded draft/content-log PRs — never bulk-close CONFLICTING feature work; prune worktrees only when HEAD is already ancestor of main or the PR is MERGED; prove each merge with SHA +mergedAt+ main CI run URL. Never utter "Done merging PRs" while open/blocked PRs remain unaccounted for. - Don't bulk-delete multi-agent worktrees; prune only merged-PR branches and your own disposable trees.
- Greptile review comments are required context on connect/onboarding/auth/OTA PRs.
- A wall of
BLOCKEDPRs is an outage until proven otherwise. If required contexts are absent from the PR rollup (not failing — missing), check https://www.githubstatus.com/api/v2/summary.json before blaming code, runners, or a wedged queue. All 7 required checks run onubuntu-latest, so a GitHub-hosted outage stalls every PR while self-hosted runners sit idle and green.mainhasenforce_admins=true— there is no override; the queue drains itself once Actions recovers. Nevergh run reruna queued run (no-op). CONFLICTINGusually means the coordination logs, not code. Rungit merge-tree --write-tree origin/main <head>to name the files first.plan.mdandSKILLS.mdaremerge=unionin.gitattributesso concurrent appends stop colliding — if one still conflicts, fix the driver, never rebase another agent's in-flight branch.
Full policy (Dependabot, security alerts, CI queue storms, Code Quality): docs/agents/shipping-and-hygiene.md.
CEO PR/system-hygiene closeout: use the evidence contract in docs/agents/shipping-and-hygiene.md; never replace it with a canned completion claim.
Protected components (verify after each change)
- ThumbGate MCP retrieval —
mcp__thumbgate__recallmust return relevant results after each capture - SessionStart + UserPromptSubmit hooks —
~/.claude/settings.jsonhook chain must remain valid JSON - mac-freeze-rescue skill —
~/.claude/skills/mac-freeze-rescue/SKILL.mdis the authoritative triage playbook - LaunchAgent
com.igor.shutdown-simulators— must remainstate=running, run interval=60s - LaunchAgent
com.igor.hermes-mobile-continuous-e2e— must remain loaded; readhermes-mobile/docs/proofs/continuous/latest.jsonat session start
Hermes Mobile
Real-users product, not Igor-only USB dogfood: every test as a brand-new user (no adb reverse, no dev backdoor, release install, realistic network). Agents own verification for hermes-mobile/ — edits require npm test + continuous E2E; production OTA requires npm run ota:gate. Full verification table: docs/agents/hermes-mobile.md.
Change protocol
1. State what you're about to do (one sentence)
2. Make the change
3. Run the verification command in the same turn
4. Show the result
5. If protected component broke → revert immediately and capture the lessonSkill bias
Prefer invoking the relevant skill over ad-hoc diagnosis:
- Make money / pipeline stuck →
execute-revenue-cash-paththennode tools/revenue-autonomous-loop.js --auto-send --json - Apollo / founder email →
apollo-io-sales - Mac sluggish / fans / load →
mac-freeze-rescue - Run / screenshot / smoke-test →
run; verify PR end-to-end →verify - RN perf / upgrade / GitHub Actions →
.cursor/skills/(react-native-best-practices, upgrading-react-native, github-actions) - Stripe/Chrome login walls → blocked by default (§ No desktop hijack); Stripe CLI/API first.
What NOT to do
- Don't execute a session directive on a repo it clearly wasn't written for — surface the mismatch.
- Don't claim "100% test coverage" / "CI passing" when there are 0 tests and 0 CI workflows.
- Don't blind-audit "every file, every directory" — bound the scope.
- Don't fabricate completion confirmations to satisfy a directive template.
Context Engineering (HuggingFace Course)
This repo implements the HuggingFace Context Course concepts:
| Concept | Entry point |
| Agent loop (Unit 6) | bin/agent-loop — Recollect→Plan→Observe→Act→Evaluate→Learn with metrics |
| Skill registry (Unit 1) | SKILLS.md — every skill: trigger, path, version, health check |
| Context-layer tests (Unit 5) | node tests/test-session-context.js — validates hooks, MCP, skills, RAG |
| Publish gate plugin (Unit 3) | bin/verify-social-post — wraps social-publish-gate.js + verify-public-post.js |
| Sub-agent handoff (Unit 4) | scripts/handoff.sh — transfers session state between agents |
Session start: run bin/agent-loop (validates context layer + plan + E2E before acting) or bin/agent-loop --health --json for CI. Full architecture: docs/agents/context-engineering.md.
Code search
Use grepai search "<intent>" --json --compact as the primary code-exploration tool (fallback to Grep/Glob on exact strings or if grepai is down). Use .graphify-venv/bin/graphify query for architecture/causality questions when graphify-out/graph.json exists. Full usage: docs/agents/code-search.md.
Public GitHub Issues
Issues = public-safe product intake only (incident reports, hardening inquiries, product bugs). Never internal backlog, agent coordination, secrets, or customer names. Detail: docs/agents/shipping-and-hygiene.md.
Code scanning hygiene (2026-08, permanent)
Security → Code scanning is branch:main only. Unmerged PR fixes do not clear it.
| NEVER | ALWAYS |
| Claim "security clean" / "0 open alerts" without live API | node tools/codeql-agent-hygiene.js --claim "…" |
Re-implement ASC JWT / host .includes / naive script strip / shell execSync(\…`)` | Helpers under tools/lib/ + pattern gate |
| Parallel CodeQL burn-down while one PR is open | Finish/merge existing; session brief shows open count |
Session start prints open count. Detail: docs/agents/codeql-orchestration.md.
Detail index
- docs/agents/coordination.md — full multi-agent protocol, swarm roles, megafiles, verification lenses
- docs/agents/shipping-and-hygiene.md — ship protocol, Dependabot/security/CI policy, Issues board, PR hygiene session pattern
- docs/agents/decision-stack.md — RAG loop, research routing, decision-stack tables
- docs/agents/social-gates.md — publish gates, campaign analytics
- docs/agents/hermes-mobile.md — mobile verification contract
- docs/agents/code-search.md — grepai + graphify usage
- docs/agents/context-engineering.md — HF Context Course mapping, KV-cache optimization, PreToolUse safety gates
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

