agentleFS
RedberryProductsRedberryProducts/synapse/AGENTS.md

synapse

AGENTS.md65 starsChanged 19 days agoMITView on GitHub

Guidance for any agent or contributor writing code in this repository. Read this first, then DEV.md for exact commands. For how Laravel packages work, invoke the laravel-package skill. Use the current user's request and the active GitHub issue's goal and acceptance criteria for scope. README.md and UPGRADE.md describe supported behavior; inspect implementation and tests for technical details. Synapse (redberry/synapse, namespace Redberry\Synapse\) is a Laravel package: a development dashboard for AI agents built with the Laravel AI SDK (laravel/ai). A React…

  • 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 33,315 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 repository2 other files it gives its agents.

The file

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

12 rules. About 0 are common, 5 are distinctive, and 7 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.

  • 7

    Very specific

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

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

    Run composer test:e2e: when you touch the frontend or the chat/stream surface.

    line 9
  2. Distinctive:

    Resolve scope conflicts explicitly: If the requested acceptance criteria, maintained docs, and implementation disagree, identify the …

    line 13
  3. Very specific:

    Don't write comments that restate the code: Use intention-revealing names.

    line 66
  4. Distinctive:

    Don't add a dependency: before checking whether the framework or an existing dependency already solves it.

    line 70
  5. Very specific:

    use Icons from lucide-react — no inline SVG.

    line 94
  6. Very specific:

    One behavior per it(): If the name needs "and", split it — a failure should name exactly what regressed.

    line 116
  7. Very specific:

    Test the real implementation: Use the real DB (RefreshDatabase, in-memory sqlite).

    line 118
  8. Very specific:

    Every feature ships with tests.

    line 120
  9. Very specific:

    ttfb must be a few milliseconds: If it equals total, nothing is streaming: the whole conversation is buffered and painted at once, which …

    line 178
  10. Distinctive:

    Surgical changes: Every changed line should trace to the request.

    line 242
  11. Distinctive:

    Reuse over duplication: Before writing something new, check whether it already exists (a helper, a base class, an SDK method).

    line 244
  12. Distinctive:

    Avoid duplicating implementation details across documents.

    line 259

≈ “Common” is an estimate: at least 1 in 5 of the 42,283 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

Working on Synapse

Guidance for any agent or contributor writing code in this repository. Read this first, then DEV.md for exact commands. For how Laravel packages work, invoke the laravel-package skill. Use the current user's request and the active GitHub issue's goal and acceptance criteria for scope. README.md and UPGRADE.md describe supported behavior; inspect implementation and tests for technical details.

Important notes

  • Plan before coding. For a non-trivial task, state a short plan (steps → how you'll verify each) and work through it.
  • Run the gates before reporting done: composer check (lint + analyse + test). All green, every time. A pre-commit hook enforces this — enable it once with composer hooks.
  • Run composer test:e2e when you touch the frontend or the chat/stream surface. It's excluded from composer check and from CI (needs Playwright + built assets); it is a required gate before a release.
  • Sequence feature and browser runs within a checkout. Installation tests publish/remove Testbench's temporary migrations; simultaneous suites can race. Use separate copies for concurrent compatibility checks.
  • Rebuild dist/ (npm run build) whenever resources/js changes — it's committed, and the hook checks it.
  • Never git commit without being asked.
  • Resolve scope conflicts explicitly. If the requested acceptance criteria, maintained docs, and implementation disagree, identify the discrepancy before changing behavior.

What this is

Synapse (redberry/synapse, namespace Redberry\Synapse\) is a Laravel package: a development dashboard for AI agents built with the Laravel AI SDK (laravel/ai). A React SPA served by a Laravel service provider — think Telescope/Horizon, but for AI agents. The package ships discovery, chat, recording, approvals, sources, completion explanations, and model-step inspection, with Pest, Pint, and PHPStan gates.

Repository map

src/                          # PHP — the package
├── SynapseServiceProvider.php        # register/boot: routes, views, publish, commands, schedule
├── SynapseApplicationServiceProvider.php  # compatibility base; published provider is self-contained
├── Chat/                             # invocation, approvals, recording, replay, SSE projection
├── Discovery/                        # agent metadata, tools, models, diagnostics
├── Synapse.php                       # static helpers: asset tags, script vars, auth callback
├── Http/{Controllers,Middleware}/    # HomeController (SPA shell), Authorize (viewSynapse gate)
├── Console/                          # Install / Prune / Clear commands
├── Migrations/SynapseMigration.php   # legacy migration base retained for compatibility
├── Models/                           # SynapseModel base + Conversation/Message/ToolInvocation
└── Repositories/                     # ConversationRepository (cascade delete lives here)
config/synapse.php            # publishable config (enabled, ui, discovery, playground, storage, retention)
database/migrations/          # three self-contained synapse_* tables (publish-only)
routes/web.php                # discovery/chat/approval/history/attachment APIs + SPA catch-all
resources/js/                 # React + TS SPA — elements/ → components/ → composed/ → pages/
                              #   (+ hooks, lib, types, styles)
resources/views/layout.blade.php   # SPA shell + window.Synapse bootstrap
stubs/                        # SynapseServiceProvider.stub (published viewSynapse gate)
dist/                         # compiled assets — COMMITTED, inlined at request time
workbench/                    # Testbench dev app + sample/diagnostic agents
tests/                        # Pest + Testbench (Unit/, Feature/, Browser/ e2e)
.githooks/                    # pre-commit hook (enable with `composer hooks`)
testing-laravel-project/      # gitignored real app for manual install testing (bin/setup-testing-app.sh)
references/                   # gitignored: laravel/ai, telescope, horizon (read-only reference)

Docs: README.md, UPGRADE.md, DEV.md, release checklist. Completed implementation history lives in closed GitHub issues, merged PRs, and Git history. Keep only unfinished work in plans/.

Development principles

Hierarchy of priorities

  1. Correctness — does it meet the agreed goal and acceptance criteria?
  2. Simplicity — is this the simplest solution that works?
  3. Readability — can human understand it in 30 seconds?

KISS · DRY · SOLID — applied pragmatically

  • KISS — don't over-engineer. Three similar lines beat a premature abstraction. No config options, flexibility, or helper indirection nobody asked for.
  • DRY — extract shared logic only once it appears in 2+ places with the same shape. Premature deduplication couples worse than duplication. (The ConversationRepository cascade earned extraction because prune, clear, and the conversation delete endpoint all need it.)
  • SOLID — at package scale, the parts that matter: single responsibility (a controller doesn't build SQL; a command delegates to a repository/service), and dependency inversion (services/repositories receive collaborators via constructor injection so they're testable). Prefer composition over inheritance; SynapseModel is the deliberate exception for shared framework wiring.

What NOT to do

  • Don't write comments that restate the code. Use intention-revealing names. Add docblocks only where they carry type information PHPStan needs (array shapes, generics, model @property) or explain a non-obvious why.
  • Don't silence PHPStan with @phpstan-ignore without explicit permission from developer, baseline entries, assert(), inline @var, casts, or widened types. An "always true/false" error means an annotation is wrong.
  • Don't leave // TODO/// FIXME without a concrete action.
  • Don't handle impossible errors (e.g. re-validating data a FormRequest/route-model-binding already guaranteed). One catch-all owns agent-invocation failures.
  • Don't add a dependency before checking whether the framework or an existing dependency already solves it. Justify new frontend deps by a feature that needs them.
  • Don't use mixed where a concrete type is known; narrow it. Don't reach for facades in services/repositories where constructor injection reads clearer and tests better — facades are fine at framework edges (providers, commands, controllers).
  • Don't concatenate SQL. Eloquent/query-builder bindings only.
  • Don't reformat or refactor unrelated code while making a change (see Surgical changes).
  • Don't touch the SDK's tables. synapse_* tables are fully independent of agent_conversations.

Coding standards

PHP

  • Laravel style, enforced by Pint (laravel preset) — run composer lint before committing. Don't introduce declare(strict_types=1) (not used here); match the surrounding file.
  • Type everything: params, returns, properties; constructor property promotion; @property docblocks on models.
  • PHPStan level 5 (larastan) stays green. Fix the root cause, always.
  • Small, single-concern classes.

TypeScript / React

  • Four layers, each importing only from the ones above it:
    • elements/ — generic UI primitives (button, input, dropdown, tooltip, badge…). Domain-agnostic: they know nothing about agents or conversations. If a primitive library is introduced, import it only at this layer.
    • components/ — single-purpose domain components (an agent card, a tool chip, a status badge). Presentational: data in via props, events out via callbacks. No fetching.
    • composed/ — larger units assembled from several components (app shell, grids, panels, threads). Still props-in/events-out; no route-level data loading.
    • pages/ — one per route. Owns data fetching, hooks, page state, and wiring; composes the layers above.
    • Reuse the current element inventory in resources/js/elements. Do not create a composed component for a single-use grouping unless it improves clarity.
  • React + TypeScript (strict), Tailwind v4 utilities, and local primitives in resources/js/elements (components.json points its ui alias there). Native browser controls and existing primitives are preferred; no Radix or Vercel AI client dependency is currently installed. Import via the @/ alias.
  • Logic belongs in pages and hooks, not components. A component that needs data takes it as props.
  • Theme via --color-* CSS tokens in resources/js/styles/app.css (dark-first). Never hard-code colors.
  • use Icons from lucide-react — no inline SVG.
  • Named exports; keep the bundle lean.

Naming

ThingConventionExample
Classes / enumsStudlyCaseSynapseToolInvocation
Methods / variablescamelCasedeleteConversations()
ConstantsSCREAMING_SNAKESynapse::VERSION
Config keyssnake_caseattachments_disk
DB tables / columnssnake_casesynapse_tool_invocations
Routes / URLskebab-case/synapse/api/conversations
Env varsSYNAPSE_ + SCREAMING_SNAKESYNAPSE_DB_CONNECTION
Publish tagssynapse- + kebabsynapse-config
React componentsPascalCase.tsxAppShell.tsx
Frontend lib modulescamelCase.tsapi.ts, theme.ts

Testing

Testbench + Pest. Run details in DEV.md; philosophy here.

  • One behavior per it(). If the name needs "and", split it — a failure should name exactly what regressed. Share expensive setup with beforeEach/describe, keep each test to a single assertion of intent.
  • Descriptive names: it('forbids access when the gate denies').
  • Test the real implementation. Use the real DB (RefreshDatabase, in-memory sqlite). Avoid mocks; when you must fake I/O, use Laravel's fakes (Storage::fake, Event::fake, Http::fake, Bus::fake) over mocking libraries.
  • Feature-first. Exercise real routes/commands/models over isolated units. Each test is independent.
  • Every feature ships with tests; composer test green before done.

Test tiers

TierLocationRuns inPurpose
Unittests/Unit/composer test, CIPure logic in isolation
Featuretests/Feature/composer test, CIRoutes, commands, models, repositories via the real app
Browser (e2e)tests/Browser/composer test:e2e onlyReal browser (Pest 4 + Playwright): the compiled React app mounts, renders, streams, routes

Browser tests are the only way to verify the PHP → SSE → React boundary, which is where Synapse's hardest bugs live. They are deliberately out of composer test and out of CI — they need Playwright and current dist/ assets, so they're a manual gate before releases (and worth running whenever you change the frontend).

Always drive browser tests with Agent::fake() — never call a real provider: no API spend, no flakiness, deterministic streams.

If the pre-commit hook fails but composer test passes

The hook runs composer test --quiet, which exports SHELL_VERBOSITY=-1, and Pest emits nothing at that verbosity — a failure with no output. Get at it with SHELL_VERBOSITY=-1 ./vendor/bin/pest --testsuite=unit,feature --log-junit /tmp/junit.xml.

The usual cause is a test asserting on console output, which Symfony suppresses under the same variable. Pass '-v' => true in the command's parameters; an explicit output buffer does not help, because only an input option outranks the environment.

Writing browser tests

Target with data-testid; assert content as text. These are different jobs and mixing them produces tests that pass while the UI is broken.

  • Targeting / scoping → data-testid. Pest resolves @name to [data-testid=name]. Use it to find an element to click, to assert presence/absence, and to scope a content assertion.
  • Content → real text, scoped to the element it belongs to: assertSeeIn('@tool-detail', 'Search query text'). Asserting only that @tool-description exists would pass with empty or garbled copy — exactly the bug a dashboard must never ship.
  • Interactive controls prefer their accessible name over a testid — click('[aria-label="Close info panel"]') targets and enforces a11y. Add a testid only when there's no sensible accessible name. (Pest's plain-string click() matches visible text; an icon-only button has none, and it will hang until timeout rather than fail fast.)

Add a testid only when a test needs it — never pre-emptively. Sparse, deliberate ids stay meaningful; a testid on every <div> turns the suite into structure-testing.

Gotchas worth knowing:

  • Scoped assertions run in Playwright strict mode — the text must match exactly one node inside the scope. assertSeeIn('@info-panel', 'PROVIDER') fails when the panel also contains "PROVIDER OPTIONS". Pick unambiguous strings.
  • Text assertions don't wait for a re-render; element assertions do. After an interaction, prefer assertPresent / assertMissing over assertSee / assertDontSee.
  • type() resolves fields by name/id, not by label. Pass a testid — type('@composer-input', '…'). A field with only an aria-label hangs until timeout.
  • The harness captures a streamed body in its own output buffer (ob_start() → sendContent() → ob_get_clean()), so anything that calls ob_flush() sends its bytes to stdout and hands the browser nothing. Guard the flush on PHP_SAPI, never on headers_sent() — see StreamEmitter::shouldFlush() and tests/Feature/Chat/StreamFlushTest.php.
  • No browser test can observe a mid-stream state. That same buffer means every SSE part reaches the page in one chunk, however long the run takes — a pending tool card is already success by the time the DOM exists. Assert the end state in a browser test and the streaming itself against a real server (below).
  • The harness cannot upload a file. It parses only application/x-www-form-urlencoded bodies and passes an empty files array to Request::create() (a @TODO in pest-plugin-browser). Browser tests can drive the composer as far as the chip; everything past it belongs in a feature test with a real multipart request.
  • All conversational agents share one fake gateway (the decorator's), so calling fakeAgent() twice with different responses replaces the first. A test needing two agents to behave differently passes one closure keyed on the prompt.
  • SDK 1.3 fakes discard tool calls attached to a TextResponse. For a response containing both narration and tool calls, use StepSequenceAgent middleware fixtures with public StepResponse objects. They exercise the SDK loop without provider I/O; keep fakeAgent() registered as the network guard.
  • Faked responses given as a list don't advance past a throwing entry. The SDK's fake increments its cursor with tap() after marshalling, so an entry that throws is returned forever. Use a closure keyed on the prompt when a test needs a failure followed by a success.

Verifying that it actually streams

Neither tier can: both run Laravel in-process on the CLI SAPI, where flushing is deliberately off. Streaming is only real over HTTP, so check it against testing-laravel-project — and check it after any change to StreamEmitter or the controller's stream closure.

curl -sN -o /dev/null -X POST http://127.0.0.1:8000/synapse/api/chat/app.agents.slow-tool-agent/send -b cookies.txt -H "X-XSRF-TOKEN: $TOKEN" -H 'Content-Type: application/json' -d '{"message":"Query the analytics service with seconds=4."}' -w 'ttfb=%{time_starttransfer}s total=%{time_total}s\n'

ttfb must be a few milliseconds. If it equals total, nothing is streaming: the whole conversation is buffered and painted at once, which looks like a hang and then a jump. That is precisely the regression StreamFlushTest exists to prevent.

bin/check-streaming.sh wraps this — it fetches its own CSRF token, measures, and exits non-zero when TTFB and total converge:

bin/check-streaming.sh http://127.0.0.1:8000 app.agents.slow-tool-agent

Never pipe curl into another process to inspect a stream. A pipe block-buffers and makes a healthy stream look batched — this produced two false diagnoses while the original bug was being found. Use -w with the body discarded, or os.read() on the raw fd.

SlowToolAgent / SlowTool are the fixtures for this. Every other tool returns in microseconds, so its tool-input-available and tool-output-available land in the same TCP segment and the card renders already green — the pending state is real but unobservable. SlowTool sleeps for a requested 0–5 seconds, which holds the amber card open long enough to watch in the playground.

What to test

LayerWhat to test
Configdefaults, env resolution, the production route-guard
Migrations / modelstables exist, casts, uuid7 keys, relationships
Repositoriescascade deletion, prune windows
Commandsbehavior, output, side effects
Controllers / APIstatus codes, response contract, auth gate
Discoveryfinds agents, classifies tools, extracts metadata
RecorderSDK event → synapse_tool_invocations row lifecycle

Don't test: framework internals, Eloquent itself, laravel/ai behavior, trivial accessors.

Synapse golden rules

  1. Never touch the SDK's tables. Synapse is a dev tool, not a production logger.
  2. Mirror the agent, don't fake it. Conversational agents get full history; stateless agents get one message per turn.
  3. One catch-all owns errors. Any \Throwable during invocation (including a throwing tool handle()) becomes an inline error card.
  4. config() at runtime, env() only in config files. Keeps config:cache safe.
  5. Store replay data in the SDK's own serialization shapes (Step::toArray(), TextUsage::toArray(), SDK file serialization). Private steps and ordered display parts have distinct roles; tool observations live in synapse_tool_invocations. See MessageHistory, ConversationPresenter, and the recording tests for the replay/display contract. All agents are wrapped; the original capabilities determine whether history is supplied. Failover capture retains completed results before the next provider attempt replaces its context.
  6. Cascade deletes in ConversationRepository, never DB foreign keys.
  7. dist/ is committed; references/ and testing-laravel-project/ are gitignored.

Learning from references/

references/ holds read-only copies (gitignored) to learn patterns from — study, don't copy verbatim:

PatternWhere
Install command flow (publish tags + register provider)references/telescope/src/Console/InstallCommand.php
App service provider + view* gatereferences/telescope/src/TelescopeApplicationServiceProvider.php
SPA serving (blade shell, catch-all, asset helpers)references/horizon/ (HomeController, Horizon.php, routes/web.php)
Migration connection basereferences/laravel/ai/src/Migrations/AiMigration.php
SDK events / contracts / streaming eventsreferences/laravel/ai/src/{Events,Contracts,Streaming}
Conversation store round-trip (message rehydration)references/laravel/ai/src/Storage/DatabaseConversationStore.php

Writing-code principles

  1. Think before coding. State assumptions; if multiple interpretations exist, surface them rather than picking silently; if something's unclear, ask.
  2. Simplicity first. Minimum code that solves the problem — nothing speculative. If 200 lines could be 50, rewrite.
  3. Surgical changes. Every changed line should trace to the request. Don't "improve" adjacent code, comments, or formatting. Match existing style. Remove orphans your change created; leave pre-existing dead code (mention it).
  4. Goal-driven. Turn tasks into verifiable goals: "fix the bug" → write a failing test that reproduces it, then make it pass.
  5. Reuse over duplication. Before writing something new, check whether it already exists (a helper, a base class, an SDK method). If it needs refactoring to reuse, ask first and explain what's needed.

Keeping docs in sync

This repo deliberately keeps its docs synchronized. When your change affects one, update it:

ChangeUpdate
A technical decision / mechanismExplain it in the PR; update AGENTS.md only for lasting contributor guidance
User-visible behaviorREADME.md, plus UPGRADE.md when migration steps change
Coding conventions / patterns / standardsAGENTS.md (this file)
Dev commands / workflowDEV.md
Laravel-package methodologythe laravel-package skill
Quick-start / prerequisitesREADME.md

Avoid duplicating implementation details across documents. Feature plans belong to unfinished work; remove completed plans and their unused assets when their issue/PR records provide the history.

Quick reference: task → location

You need to…Go to…
Add an API endpointroutes/web.php (/api group, before the catch-all) + src/Http/Controllers
Add business logica service in src/ (e.g. Discovery/, Recording/)
Add a DB tabledatabase/migrations/ (extend Laravel's Migration and keep the file independent of Synapse classes)
Add a modelsrc/Models/ (extend SynapseModel)
Add a commandsrc/Console/ + register in SynapseServiceProvider
Add configconfig/synapse.php
Add a React pageresources/js/pages/ + router.tsx
Add a UI primitiveresources/js/elements/ (shadcn ui alias points here)
Add a domain componentresources/js/components/
Assemble several componentsresources/js/composed/
Add a sample agentworkbench/app/Agents/
Add a testtests/Feature/ (or tests/Unit/)
Add a browser e2e testtests/Browser/ — run with composer test:e2e
Check feature scopeCurrent user request + active GitHub issue acceptance criteria
Check dev commandsDEV.md

Definition of done

  • Meets the agreed goal and acceptance criteria.
  • Covered by Pest tests; composer check green (lint + analyse + test).
  • composer test:e2e green if the frontend or chat/stream surface changed.
  • dist/ rebuilt if resources/js changed.
  • Maintained docs updated where behavior, upgrade steps, or contributor guidance changed.

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.