syrus
CLAUDE.md9 starsChanged 8 days agoMITView on GitHub
A multi-user, cross-repo issue→PR automation harness. Owns the deterministic plumbing (clones, branches, PRs, cleanup) so the agent can focus on writing code. See README.md for the human pitch and ROADMAP.md for milestone planning. Never name a private Syrus instance's records in prose. JOB-<id>, EPIC-<id>, WF-<id>, RUN-<id>, chat IDs, private instance hostnames, and private repository incident labels must not appear in comments, spec descriptions, commit-adjacent docs, or any file under config/syrus_docs/ / website/ / a plugin's docs/. They mean nothing to…
In this repository3 other files it gives its agents.
- implementSkill
- rebaseSkill
- syrus-debugSkill
The file
We split this CLAUDE.md into the rules it gives an agent
10 rules. About 0 are common, 5 are distinctive, and 5 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.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 33
Test fixture values are fine as-is.
- Very specific: line 138
Never read content through GithubClient directly -- spec/architecture/repository_content_reads_spec.rb enforces it -- and never treat …
- Distinctive: line 150
Read the reference file that matches the work in front of you:
- Very specific: line 191
Keep contributor conventions in docs/engineering/conventions/.
- Very specific: line 201
Add new Job, Workflow, or Step metadata in Job::Kind, Workflow::TriggerKind, or Step::Kind rather than scattering constants.
- Distinctive: line 204
Do not add core references that make bundled plugins undeletable.
- Distinctive: line 217
Collapsed tool-card headers are operator design-locked: Every collapsed generic, core, plugin, pending, completed, failed, grouped, and …
- Distinctive: line 234
When drafting work for chat, keep proposals finishable inside one bounded implementation attempt.
- Very specific: line 240
Use git diff <base>...HEAD for three-dot diffs.
- Distinctive: line 266
If the test would require infrastructure that doesn't exist in the test environment (e.g.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.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
Syrus — agent guide
A multi-user, cross-repo issue→PR automation harness. Owns the
deterministic plumbing (clones, branches, PRs, cleanup) so the
agent can focus on writing code. See README.md for the human pitch
and ROADMAP.md for milestone planning.
Repository hygiene
Never name a private Syrus instance's records in prose. JOB-<id>,
EPIC-<id>, WF-<id>, RUN-<id>, chat IDs, private instance hostnames, and
private repository incident labels must not appear in comments, spec
descriptions, commit-adjacent docs, or any file under config/syrus_docs/ /
website/ / a plugin's docs/. They mean nothing to anyone outside that one
instance, and they go stale the moment the record is archived.
The moment this bites is right after you debug a production incident, when
the natural thing to write is # Regression for WF-29556: or
# this was JOB-409's root cause. Write the explanation instead — the
identifier was only ever standing in for it:
# Bad # Good
# Regression for WF-29556: ... # Regression: ...
# the WF-480 run storm # a production run storm
# matching JOB-5025's delete-only … # matching the previous delete-only …
# WF-28163 ran 14 of them one at a … # a production workflow ran 14 of them …
# Part of EPIC-27: groundwork for … # Part of the access-control work: …This is about prose, not about identifier-shaped strings:
- Test fixture values are fine as-is.
run_id: 149674,slug: "JOB-874",EPIC-7in a component test — leave them alone, don't renumber them. - Format examples are fine:
syrus checkout JOB-<id>, "acceptsJOB-123,job-123, or123",JOB-42in a CLI doc. docs/plans/**is exempt — it is the designated home for instance-specific evidence, alongside the operator conversation.
spec/architecture/no_private_instance_identifiers_spec.rb enforces the
comment half of this mechanically; the docs half is on you.
Stack
Rails 8.1.4 · Ruby 3.4.10 · SQLite (dev/test) / MySQL (prod) ·
Solid Queue + Solid Cache + Solid Cable · React + TypeScript via Vite ·
TanStack Query · Tailwind via tailwindcss-rails · Go CLI under cli/ ·
Electron desktop under desktop/ · Octokit for GitHub.
Architecture in 60 seconds
External polling drives everything — no inbound GitHub callbacks. PollAllRepositoriesJob
fans out to one PollRepositoryJob per active repository, which lists
issues with the configured trigger label. Each new labeled issue creates
a Job (the thread), which auto-creates an initial Workflow (the
attempt), which auto-enqueues its first Step's Run. PollAllPullRequestsJob
does the same for PR review feedback, creating follow-up Workflows on
existing Jobs; PollAllExternalOpenPrsJob ingests opt-in externally
filed PRs as reviewable external_pr Jobs.
The state machines (AASM):
Job (one per issue): triaging/backlog/queued → running → implemented/approved/landing → closed
Workflow (one per attempt): queued → running → succeeded | failed | cancelled | blocked
Step (one per step): queued → running → succeeded | failed | cancelled | skipped | blocked
Run (one per step): queued → running → succeeded | failed | cancelled | skipped | blockedJob carries the GitHub identifiers (issue + PR numbers, branch name) and
the credential mode captured at creation time (app or pat).
Workflow is the top-level unit for a single attempt; it owns a chain of
Steps and a shared workspace at $SYRUS_DATA_ROOT/workflows/<workflow_id>/.
Each Step dispatches to a Steps:: handler and owns one Run. Run
carries per-attempt state — prompt, agent metadata, diff, PR copy.
Distributed grader Steps are the exception to that shared-workspace model.
They run from a recorded WorkflowSourceSnapshot in a detached immutable
checkout, and may reuse a worker-local prepared dependency layer keyed by the
repository's prepare plan and worker capabilities. Treat the snapshot as the
grader's source of truth; do not assume a grader reads the live mutable
workflow checkout. Commands run through Execution::Router: enabled
:execution_backend providers may claim a request, otherwise core uses
Execution::Local unless the workload policy is fail-closed. Keep alternate
execution and confinement in that provider contract rather than branching in
grader or chat call sites.
Job#kind is registered through Job::Kind: built-ins include issue
(labeled work item), cron (scheduled fire), direct (operator prompt),
main_grader and deploy (infrastructure), and external_pr (an ingested
outside PR). Investigation-only Jobs are a flag on investigable kinds, not a
separate kind. Plugins may contribute additional kinds through
:workflow_kinds (for example, Coworkers contributes its background task
kind); do not hard-code kind lists.
WorkUnit / WorkIntent / WorkDefinition (app/models/work_unit.rb,
app/models/work_intent.rb, app/services/work_definitions/) is the
ownership/scheduling layer above the AASM machines, not a replacement for
them: WorkUnits::Launcher.start! still always
falls through to StepDispatcher.start_workflow, which remains the actual
execution engine. WorkIntent is the durable "we want this work done"
record; WorkUnit is one runtime attempt at it, holding WorkUnitLocks
(mutex per job/epic/repo/landing-slot) and WorkUnitMembers.
WorkDefinitions::Base subclasses (built-ins plus plugin contributions —
Initial, Rebase, AutoMerge, MergeTrain, JobBundle, etc., registered
by kind) centralize retry/lock/landing policy that used to be scattered across
StepDispatcher and landing-queue services. WorkUnits::PathOwnership maps
each concrete path
(retry/resume/pause, auto_merge/merge_train/stack_rebase, reconciler repairs)
to WorkUnit ownership directly. The old shadow-mode and ownership-cutover
feature flags have been removed; compatibility now lives in
presentation/diagnostic fallbacks, not in the launch funnel.
WorkEngine::Reconciler targets repairs at WorkUnit/WorkIntent records
first. Admin surface: /admin/work_units, with normal Job-page WorkUnit
internals gated by AppSetting.show_work_unit_debug?.
Jobs and Workflows carry a PlannedExecutionRequirement for the mutable
primary implementation workspace. Its placement contract is explicitly
declared (currently by OS, defaulting to Linux), never inferred from proposal
prose. Immutable distributed grader targets have a separate capability
contract from .syrus.yml; target requirements may additionally constrain
architecture, toolchain, and runtime. Workers advertise capabilities via
SYRUS_WORKER_CAPABILITIES plus local probes, and RunQueueResolver routes or
blocks starts (no_capable_worker) when no live worker satisfies the applicable
contract. See the placement architecture rather than treating the two
contracts as interchangeable.
Repository content (app/services/repository_content.rb) is how Syrus
reads a repository without cloning it: the pre-workflow .syrus.yml read,
preview projects, skills, the Job source browser and diff viewer, read_pr.
RepositoryContent.for(repository).resolve(ref) gives an immutable revision;
tree/read/changes read at it and are cached. Answers come from
repository_content_provider plugins, replicas before upstreams:
git_mirror (a local mirror service run through plugin_runtime) first,
github_host (the GitHub API) after. NotFound is a final answer;
Unavailable/Unsupported/UnknownRevision fall through to the next
provider, and Truncated carries a partial answer only display code may use.
Never read content through GithubClient directly --
spec/architecture/repository_content_reads_spec.rb enforces it -- and never
treat Unavailable as "the file does not exist". Core specs read through a
fake provider by default (spec/support/repository_content.rb,
stub_repository_content).
Progressive disclosure
AGENTS.md is a symlink to this file. Keep the root guide slim enough for
Muse-backed agents to load at startup, and put deep detail behind explicit
references instead of expanding this file in place.
Read the reference file that matches the work in front of you:
- Engineering documentation — agent-neutral routing, ownership, and precedence for current engineering knowledge.
- Architecture — domain model, workflow execution, repository content, chat, plugins, and frontend.
- Conventions — focused implementation, frontend, plugin, migration, deployment, and testing guides.
- Operations — deployment, production debugging, and workflow recovery.
- Maps and pitfalls — subsystem navigation and recurring failure modes.
- .claude/skills/implement/SKILL.md — live implement-step prompt instructions.
- .claude/skills/rebase/SKILL.md — live rebase and stack-rebase prompt instructions.
- .claude/skills/syrus-debug/SKILL.md — live operational debugging instructions.
Conventions summary
Public docs, operator docs, prompt source, plugin boundaries, localization, CLI/API behavior, desktop behavior, workflow registries, credentials, queues, migrations, and tests all have detailed rules in engineering conventions. Before editing any of those surfaces, read the relevant focused guide and follow the local convention instead of inventing a parallel pattern.
High-frequency reminders:
- Public website/docs stay current. Product-facing behavior changes must
update
website/in the same PR. - Keep searchable harness docs audience-safe.
config/syrus_docs/is searchable by chat and implementation agents working on any project. Put only behavior and functionality needed to use Syrus there:.syrus.ymlkeys, operator settings and feature flags, workflow steps and trigger kinds, review/grader/landing/merge behavior, MCP tool semantics, permission behavior as it affects agents, and user-visible features. Internal-only changes such as response compression, payload shapes, caching, or polling do not require aconfig/syrus_docs/page. - Keep contributor conventions in
docs/engineering/conventions/; internal architecture, data models, and telemetry indocs/engineering/architecture/(with maps indocs/engineering/maps/); runbooks for running, deploying, scaling, and upgrading Syrus indocs/engineering/operations/; plugin- authoring guidance indocs/engineering/conventions/plugins.md; durable choices indocs/engineering/decisions/; and recurring failure modes indocs/engineering/pitfalls/. Do not put internal code/class/file/database details, telemetry or audit tables, internal data APIs, incident post-mortems, or historical “we used to” material inconfig/syrus_docs/. - Preserve
AGENTS.md -> CLAUDE.md; edit the shared guidance through this file. - Add new Job, Workflow, or Step metadata in
Job::Kind,Workflow::TriggerKind, orStep::Kindrather than scattering constants; plugin-owned workflow kinds belong behind the:workflow_kindsprovider. - Do not add core references that make bundled plugins undeletable; plugin-owned tools, docs, routes, and specs belong with the plugin.
- Localize user-visible SPA copy with i18next and server/API copy with Rails I18n; add matching English, German, and Latin keys, and keep machine-readable API error codes separate from translated messages.
- New chat-facing MCP tools need an explicit rendering decision: add a tool card
under
app/frontend/routes/chat/tool_cards/orplugins/<name>/app/frontend/tool_cards/, or register an explicitgeneric/hidden/deferredstatus inAdmin::McpToolCardCoverage::EXPLICIT_CARD_STATUSES. - Bump the top-level JSON API
vonly for breaking payload changes. Syrus supports one current version with no compatibility shims, so update the web, ActionCable, inline bootstrap, desktop, and CLI consumers in the same change. - Collapsed tool-card headers are operator design-locked. Every collapsed generic, core, plugin, pending, completed, failed, grouped, and single-call tool card is exactly one visual line at every width, ordered disclosure marker, non-wrapping title, outcome pill, optional metadata/count pills, then a clipped or ellipsized details preview using only the remaining width. Preview whitespace is normalized; pills never wrap, stack, reorder, or disappear; and the row never creates horizontal overflow. Full details remain available after expansion. Tool-specific cards may provide labels and summaries but may not alter this shared geometry. The shared implementation and its component, browser-geometry, and architecture assertions/fixtures must not be removed, weakened, or updated to permit wrapping without explicit written approval from Thomas Kadauke.
- Searchable/filterable product surfaces use the shared Filters AST and
FilterBar; deliberately decide whether the surface also needsSmartFolderpersistence. SmartFolder-backed endpoints must return and apply the same effective filter and include the shared contract examples inspec/support/shared_examples/smart_folder_filter_bar_contract.rb. - When drafting work for chat, keep proposals finishable inside one bounded implementation attempt. Do not ask a Job to dogfood, burn in, monitor production, or wait for future operator action; avoid brand-new Epics with only one child Job.
- Generate migrations with
bin/rails generate migration, make them idempotent, and avoid JSON column database defaults on MySQL. - Use
git diff <base>...HEADfor three-dot diffs.
Tests are not optional
Every PR must include tests for the behavior it changes. PRs without tests will not be merged. This applies to every kind of change — new features, bug fixes, refactors, plumbing, "trivial" tweaks. If the change is too small to justify a test, the change is too small to need a PR; fold it into something testable.
What "with tests" means here:
- New behavior → a spec that fails without your change and passes with it. If you can't write one, the behavior isn't well-defined yet.
- Bug fix → a regression spec that reproduces the bug. The fix without the spec is half a fix; nothing stops it from regressing.
- Refactor → existing specs must still pass, AND if the refactor touches an under-tested area, add the missing coverage as part of the same PR. "I didn't change behavior" is not a free pass.
- Anything touching the agent loop, RunJob, AgentInvocation, MCP,
or the polling jobs → exercise it with the existing test seams
(
RunJob.agent_runner,PrSummarizer.runner, WebMock for Octokit, stubbed AgentInvocation Result). These seams exist precisely so every code path can be tested without shelling out to real claude or hitting real GitHub.
If the test would require infrastructure that doesn't exist in the test environment (e.g. SolidQueue tables aren't loaded in test — test runs single-database), stub the boundary and say so in a comment. Don't skip the test.
The suite is large. During implementation, run the narrowest useful local
validation: the exact failing example, the smallest affected spec file, or the
focused frontend test file. Syrus runs typed framework graders from
.syrus.yml after agentic steps for broader feedback.
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.

