agentleFS
IgorGanapolskyIgorGanapolsky/mac-yolo-safeguards/AGENTS.md

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

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
  1. Very specific:

    Never issue a canned completion statement ("Done", "Shipped", "All clean") without verifiable evidence in the same response.

    line 23
  2. Very specific:

    Prefer "I believe this is done, verifying now..." until verification completes.

    line 24
  3. Distinctive:

    If something failed, partial, or unknown — say so.

    line 25
  4. Very specific:

    If you hallucinate, over-claim, or operate on stale assumptions: capture via mcp__thumbgate__capture_memory_feedback with signal=down.

    line 26
  5. Distinctive:

    Every claim needs proof in the same turn: deletions → before/after counts.

    line 28
  6. Common:

    Read-write + execute by default.

    line 36
  7. Distinctive:

    Never tell the user to run commands, tap UI, or "do X yourself." Execute what you can, automate what repeats, report what was done + …

    line 40
  8. Distinctive:

    Don't add features, abstractions, error handling, or tests for scenarios that can't happen.

    line 48
  9. Distinctive:

    Don't write hooks, configs, or CI workflows speculatively — wire them only on a concrete trigger.

    line 49
  10. Very specific:

    Decision stack: before non-trivial decisions or ship claims run the evidence stack (tools/agent-session-start.js, …

    line 56
  11. Very specific:

    Coding context pack (issue-first): before multi-file product coding, load node tools/coding-context-pack.js (auto on session-start as …

    line 57
  12. Very specific:

    Never write secrets to tracked files: If a credential lands in chat: refuse to use it, don't store it, flag for rotation.

    line 67
  13. Very specific:

    business_os/ is gitignored internal ops data: Do not modify without explicit per-file consent.

    line 69
  14. Very specific:

    CONFLICTING usually means the coordination logs, not code: Run git merge-tree --write-tree origin/main <head> to name the files first.

    line 81
  15. Distinctive:

    CEO PR/system-hygiene closeout: use the evidence contract in docs/agents/shipping-and-hygiene.md.

    line 85
  16. Distinctive:

    Prefer invoking the relevant skill over ad-hoc diagnosis:

    line 111
  17. Very specific:

    Run / screenshot / smoke-test → run.

    line 115
  18. Distinctive:

    Don't execute a session directive on a repo it clearly wasn't written for — surface the mismatch.

    line 121
  19. Distinctive:

    Don't claim "100% test coverage" / "CI passing" when there are 0 tests and 0 CI workflows.

    line 122
  20. Distinctive:

    Don't blind-audit "every file, every directory" — bound the scope.

    line 123
  21. Distinctive:

    Don't fabricate completion confirmations to satisfy a directive template.

    line 124
  22. Very specific:

    Session start: run bin/agent-loop (validates context layer + plan + E2E before acting) or bin/agent-loop --health --json for CI.

    line 138
  23. Very specific:

    Use grepai search "<intent>" --json --compact as the primary code-exploration tool (fallback to Grep/Glob on exact strings or if grepai is …

    line 142

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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 task blocked, 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

  1. Never issue a canned completion statement ("Done", "Shipped", "All clean") without verifiable evidence in the same response.
  2. Prefer "I believe this is done, verifying now..." until verification completes.
  3. If something failed, partial, or unknown — say so. Lying or hedging is a directive violation.
  4. If you hallucinate, over-claim, or operate on stale assumptions: capture via mcp__thumbgate__capture_memory_feedback with signal=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__recall at session start; capture every fix/incident with concrete artifacts (dates, PIDs, paths, metrics). Recurring bug class → deterministic check in tools/ wired into CI.
  • Research: parallel-cli search by 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 via npx expo install --fix in 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: true on main); prefer gh pr merge --auto --squash. A "ready" PR must be up-to-date with main; 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 via gh pr list --state merged + git push origin --delete <head> only when no open PR uses that head — never require merge-base --is-ancestor for 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 BLOCKED PRs 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 on ubuntu-latest, so a GitHub-hosted outage stalls every PR while self-hosted runners sit idle and green. main has enforce_admins=true — there is no override; the queue drains itself once Actions recovers. Never gh run rerun a queued run (no-op).
  • CONFLICTING usually means the coordination logs, not code. Run git merge-tree --write-tree origin/main <head> to name the files first. plan.md and SKILLS.md are merge=union in .gitattributes so 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)

  1. ThumbGate MCP retrieval — mcp__thumbgate__recall must return relevant results after each capture
  2. SessionStart + UserPromptSubmit hooks — ~/.claude/settings.json hook chain must remain valid JSON
  3. mac-freeze-rescue skill — ~/.claude/skills/mac-freeze-rescue/SKILL.md is the authoritative triage playbook
  4. LaunchAgent com.igor.shutdown-simulators — must remain state=running, run interval=60s
  5. LaunchAgent com.igor.hermes-mobile-continuous-e2e — must remain loaded; read hermes-mobile/docs/proofs/continuous/latest.json at 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 lesson

Skill bias

Prefer invoking the relevant skill over ad-hoc diagnosis:

  • Make money / pipeline stuck → execute-revenue-cash-path then node 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:

ConceptEntry 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.

NEVERALWAYS
Claim "security clean" / "0 open alerts" without live APInode 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 openFinish/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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.