agentleFS
rebornixrebornix/Agmente/Agmente/AGENTS.md

Agmente / Agmente

AGENTS.md545 starsChanged 9 months agoMITView on GitHub

The file

We split this AGENTS.md into the rules it gives an agent

8 rules. About 0 are common, 5 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use AGMENTE_ACP_REPO and AGMENTE_CODEX_REPO entries instead of machine-specific absolute paths.

    line 11
  2. Very specific:

    Use persistExtendedHistory: true on thread/start and thread/resume so cold app relaunch can recover richer tool-call history from …

    line 33
  3. Distinctive:

    Add-server form or summary dialog changes must keep ACP and Codex messaging clearly separated.

    line 47
  4. Distinctive:

    If changing initialization/protocol detection, validate ACP and Codex paths.

    line 50
  5. Distinctive:

    If changing session/thread metadata parsing, verify list + open-session behavior.

    line 51
  6. Very specific:

    If changing Codex thread hydration or reconciliation behavior, update Agmente/specs/codex-load-resume-merge.md and the corresponding …

    line 52
  7. Distinctive:

    If changing add-server UX, verify both protocol summaries and warnings are accurate.

    line 53
  8. Distinctive:

    If adding capability toggles/settings, persist and restore via existing model/storage patterns.

    line 54

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

Agmente App Layer Guide

Scope

SwiftUI app layer and protocol routing logic:

  • Server management UI
  • Session/thread UI state
  • ACP vs Codex view model selection

External Repo Paths

  • For upstream ACP/Codex source checks, read .agmente.paths from repo root.
  • Use AGMENTE_ACP_REPO and AGMENTE_CODEX_REPO entries instead of machine-specific absolute paths.

Architecture Model

  • The app has a single coordinator that owns per-server runtime state.
  • Each server runtime follows one protocol mode at a time (ACP or Codex).
  • Protocol-specific behavior stays isolated behind a shared server view-model contract.
  • UI should rely on shared abstractions first, and branch only for protocol-specific screens/controls.

Architecture Invariants

  • AppViewModel owns one server view model per server ID.
  • ACP and Codex paths must remain protocol-isolated.
  • UI should consume unified protocol (ServerViewModelProtocol) where possible.
  • Detailed Codex load, resume, and merge behavior is specified in Agmente/specs/codex-load-resume-merge.md.
  • Selecting a different server must not persist the previously selected server's endpoint/token/cwd into the new server while rebinding published connection fields; apply stored config non-destructively, then reconnect.
  • Session/thread summaries should preserve server metadata (cwd, timestamps) when available.
  • ACP placeholder-session resolution must be non-destructive: when session/new returns a real session ID, preserve the in-memory user/assistant transcript, treat the new session as already materialized for the current connection, and avoid issuing a follow-up session/load if richer local state already exists or the fresh session is still empty.
  • ACP session persistence must never save unresolved placeholder IDs as durable sessions. When a placeholder resolves, migrate any locally cached or persisted transcript state onto the real session ID so Copilot-style reloads can reopen the same conversation instead of duplicate or blank rows.
  • ACP placeholder-session failures must be terminal for that draft: if session/new fails, clear the placeholder session selection before any prompt path can fall through to session/prompt with the placeholder ID.
  • Codex reconnect/resume must be non-destructive for active sessions: prefer richer in-memory chat/tool-call state when thread/resume is incomplete, and restore streaming/stop state from active turn status.
  • On reconnect (and open when possible), prefer non-destructive reattachment to loaded in-memory threads via addConversationListener + thread/read; only fall back to thread/resume when the thread is not loaded or listener attach is unavailable.
  • Codex turns inferred only from thread/resume are resume-derived state, not confirmed live turns: keep them locally resettable in the composer, and only restore real turn/interrupt behavior after a successful loaded-thread attach/read or a live turn notification (turn/started, item/started, item/completed).
  • For resume-based hydration paths, issue at least one follow-up thread/resume to converge eventual-consistency gaps where streaming deltas are not replayed.
  • Use persistExtendedHistory: true on thread/start and thread/resume so cold app relaunch can recover richer tool-call history from rollout-backed reads.
  • During Codex thread/read merge, preserve local rich assistant rows (tool calls/thoughts) while suppressing duplicate markdown-only assistant inserts already represented by those rows; per-turn ordering must remain user-first before assistant output.
  • Plan mode output must map to .plan assistant segments from Codex notifications (item/plan/delta, turn/plan/updated) and from completed assistant message payloads containing <proposed_plan>...</proposed_plan>.
  • For plan streaming, prefer typed app-server notifications (for example item/plan/delta) over mirrored raw codex/event/* notifications to avoid duplicate rendering.
  • Codex permissions selector maps to turn/start overrides on every turn:
    • Default permissions => approvalPolicy: "on-request" + sandboxPolicy.type: "workspaceWrite"
    • Full access => approvalPolicy: "never" + sandboxPolicy.type: "dangerFullAccess" (dangerous/high-risk mode)

Change Impact Rules

  • Protocol detection changes must validate both first-connect and reconnect behavior.
  • Session/thread list parsing changes must preserve ordering and metadata consistency.
  • Open-session behavior must not regress summary metadata or current working directory display.
  • Reconnect/background-resume changes must verify active-thread resubscription, streaming indicator state, and stop/send button behavior.
  • For Codex, stop/send availability must follow active turn state, not only the presence of a streaming assistant row.
  • Add-server form or summary dialog changes must keep ACP and Codex messaging clearly separated.

Contribution Checklist

  • If changing initialization/protocol detection, validate ACP and Codex paths.
  • If changing session/thread metadata parsing, verify list + open-session behavior.
  • If changing Codex thread hydration or reconciliation behavior, update Agmente/specs/codex-load-resume-merge.md and the corresponding fixtures under AgmenteTests/Fixtures/CodexThreadReadMerge/.
  • If changing add-server UX, verify both protocol summaries and warnings are accurate.
  • If adding capability toggles/settings, persist and restore via existing model/storage patterns.

Required Tests

  • CodexServerViewModelTests
  • ViewModelSyncTests
  • ACPSessionViewModelTests (when chat/session behavior changes)
  • Relevant AgmenteUITests coverage (when UI flow or accessibility IDs change)
  • Manual scenario: copilot-smoke.md when changing ACP protocol adoption, ACP/Codex mode routing, add-server ACP defaults, session/list cwd fanout, fresh-session lifecycle, or reconnect/load behavior

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.