agentleFS
atretyak1985atretyak1985/swarmery/CLAUDE.md

swarmery

CLAUDE.md7 starsChanged 40 days agoApache-2.0View on GitHub

swarmery is a Claude Code plugin marketplace (.claude-plugin/marketplace.json), not an application. It ships one vendor-neutral core plugin plus opt-in domain packs (uav-pack, iot-pack, web-pack, infra-pack, lsp-pack, claude-eng-pack, graphify-pack, graft-pack, architecture-pack, jira-pack, accounts-pack, design-pack, review-pack). Consumer projects enable plugins via their own .claude/settings.json and supply per-project flavor at runtime through .claude/project.json — nothing project-specific is ever baked into this repo. There is no build step for the marketplace itself. "Source code" here is agent/skill/command markdown, bash hooks and CLI scripts, and…

  • Reads credentials
  • Commits and pushes

The file

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

3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Keep going while the work is still yours to do.

    line 101
  2. Very specific:

    Never re-register the local checkout as a marketplace: marketplace.json name is swarmery, and a local-path registration would replace the …

    line 149
  3. Very specific:

    Every real agent routing bug or output-contract regression should become a promptfoo test case in evals/ (prefer contains/regex for hard …

    line 156

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

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

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repo is

swarmery is a Claude Code plugin marketplace (.claude-plugin/marketplace.json), not an application. It ships one vendor-neutral core plugin plus opt-in domain packs (uav-pack, iot-pack, web-pack, infra-pack, lsp-pack, claude-eng-pack, graphify-pack, graft-pack, architecture-pack, jira-pack, accounts-pack, design-pack, review-pack). Consumer projects enable plugins via their own .claude/settings.json and supply per-project flavor at runtime through .claude/project.json — nothing project-specific is ever baked into this repo.

There is no build step for the marketplace itself. "Source code" here is agent/skill/command markdown, bash hooks and CLI scripts, and JSON manifests.

Exception — tools/swarmery/: a Go + React control plane for monitoring Claude Code agent sessions — a single Go daemon with an embedded React SPA (go:embed) that indexes session transcripts from ~/.claude/projects/ into local SQLite and serves a dashboard on :7777. Own module (github.com/atretyak1985/swarmery/tools/swarmery), own build (make build), dedicated CI (.github/workflows/swarmery-ci.yml). It is NOT a plugin and is excluded from marketplace rules (neutrality scan covers plugins/** only). The committed tools/swarmery/docs/plan/ tree is the historical record of already-shipped phases only — NEW plans, specs, and design docs go to the private workspace (see "Work artifacts" below), never into this repo.

Exception — tools/notch/: a native SwiftPM macOS 14+ companion for the tools/swarmery daemon above — a small tab docked to the right screen edge (Grammarly-style; SWARMERY_NOTCH_PLACEMENT=notch restores the original notch/top-edge placement) that expands into a side panel on its own when an operator is needed (a pending approval, a failed session). Zero external dependencies (Package.swift dependencies: []): reads GET /api/sessions|/api/approvals|/api/usage and the GET /api/ws event stream from the daemon and installs no Claude Code hooks of its own. Own module (swift build/swift test, no Xcode project), own CI (.github/workflows/notch-ci.yml, macos-latest, path-filtered to tools/notch/**), own release workflow (.github/workflows/notch-release.yml on notch-v* tags). It is NOT a plugin and is excluded from marketplace rules the same way tools/swarmery is (neutrality scan covers plugins/** only). Packaging/install ergonomics live in tools/notch/Makefile (bundle/install/uninstall/restart, mirroring tools/swarmery/Makefile's copy-then-rename + launchctl kickstart -k pattern); see tools/notch/README.md for the Gatekeeper note (it ships unsigned).

Commands

Local equivalents of marketplace CI (.github/workflows/ci.yml):

# Validate all JSON manifests
node -e "JSON.parse(require('fs').readFileSync('<file>'))"   # marketplace.json, plugin.json, hooks.json, overlays/*.json

# Shell syntax + lint on all scripts (CI floor is -S error; default severity is the stricter local signal)
find plugins scripts -name '*.sh' -exec bash -n {} \;
find plugins scripts -name '*.sh' -print0 | xargs -0 shellcheck -S error

# Hook behavioral tests
bash scripts/tests/protect-sensitive-files.test.sh

# Neutrality scan — must report "✓ clean" (token patterns come from gitignored
# .flavor-tokens / .flavor-tokens-domain files or FLAVOR_BRAND / FLAVOR_DOMAIN env vars)
bash scripts/scan-flavor.sh

CI also runs a gitleaks secret scan over full git history (.gitleaks.toml).

tools/swarmery (CI: swarmery-ci.yml enforces a gated Go coverage floor of 70%, excluding cmd/swarmery, web, internal/docsfs):

cd tools/swarmery
make build          # snapshot docs → vite bundle → go:embed → single ./swarmery binary
make test           # go vet ./... && go test ./...
go test ./internal/store -run TestName   # single test
make dev            # go daemon + vite dev server (proxies /api to :7777)
make install        # rebuild + swap the service-managed binary and restart it (launchd on macOS, systemd --user on Linux)

cd web && npm run build   # includes tsc --noEmit (React 19 + Vite 8 + Tailwind 4)
cd web && npm test        # vitest + jsdom, the web app's unit/component tests (also in swarmery-ci)

Releases of the control plane are cut by pushing a swarmery-v* tag (swarmery-release.yml).

Agent evals (promptfoo golden tests for tech-lead, commit-message, guardrail-checker — not in CI, costs API tokens):

cd evals
export ANTHROPIC_API_KEY=…
npx promptfoo@latest eval        # run suite
npx promptfoo@latest view        # inspect results

CI also enforces that every plugins/*/agents/*.md has name: and description: frontmatter within the first 15 lines, starting with a --- line.

Layout

  • .claude-plugin/marketplace.json — marketplace manifest listing all plugins.
  • plugins/<name>/.claude-plugin/plugin.json — each plugin's manifest with explicit semver (bump it on any change so consumers adopt via /plugin update).
  • plugins/<name>/{agents,skills,commands,hooks,bin,templates}/ — components live at the plugin root, only plugin.json is under .claude-plugin/.
  • overlays/_schema/project.schema.json — schema for consumers' .claude/project.json; overlays/example/ is the reference overlay.
  • scripts/init.sh — one-command consumer bootstrap (settings.json + project.json skeleton + workspace namespace).
  • plugins/core/bin/agent-work.sh — project-aware workspace CLI (setup|init|phase|pause|resume|complete|archive|restore|index|list|search|view|metrics|cleanup). Resolves the workspace via AGENT_WORKSPACE_ROOT + AGENT_PROJECT env; work artifacts (plans/sessions/tasks) live in a separate private workspace repo, never here.
  • tools/swarmery/ — Go + React session-monitoring control plane (see exception note above): cmd/swarmery/, config/, internal/ (focused packages — store, ingest, api, approvals, cost, sysscan, wsingest, …), web/ (React SPA), testdata/fixtures/, docs/{jsonl-format.md,plan/}. A saved plan is revised through the dashboard's revise flow (tools/swarmery/docs/plan-revisions.md): markdown stays the source of truth — a revision is a staged proposal until the operator applies it.

Work artifacts (hard rule)

ALL new plans, specs, and design docs — including ones for tools/swarmery — are written to the private workspace repo inside the task dir: <workspace>/swarmery/workspace/working/{YYYY}/{MM}/{DD}/{slug}/plan/ (the workspace root defaults to $HOME/swarmery-workspace, overridable per machine via AGENT_WORKSPACE_ROOT / SWARMERY_WORKSPACE_ROOT; date = task start, leaf folder = kebab slug without a date prefix — the date lives only in the YYYY/MM/DD path; the canonical task-id yyyy-mm-dd-slug is derived, never encoded in the folder name). Plan structure: plan/README.md (objective, architecture decisions with real file paths, phase sequencing table + critical path, risks, Definition of Done) + phase-N-<slug>.md docs, each with a self-contained copy-paste agent prompt, measurable acceptance criteria, and — as the doc's last section — an empty ## Completion Report stub the executor fills when the phase's last criterion is ticked (the dashboard's phase Summary tab renders that section and nothing else; a doc without it shows "no summary of the work written" over work that shipped). A plan may additionally carry an optional plan/spec.md — the WHAT/WHY with - [ ] **SC-n** — <criterion> acceptance-criteria checkboxes; when present, each phase doc's header declares a **Covers:** SC-… line and the dashboard lints coverage. Top-level plan docs are phase-N-<slug>.md; a phase's Steps are its acceptance-criteria checkboxes; the plan README must carry the | # | Phase | Doc | Depends on | sequencing table (step-NN-*.md files are legacy read-compat only). The old workspace/plans/{YYYY}/… tree is frozen history — do not add to it. Never create planning artifacts under tools/swarmery/docs/plan/ or anywhere else in this repo; the in-repo plan tree is a frozen record of shipped phases.

Hard rules

Vendor neutrality (docs/NEUTRALITY.md)

  • Brand tokens (company/product names, internal repo names, env aliases, cloud regions) are forbidden everywhere in plugins/**.
  • Domain vocabulary (drones, wearables, …) is legitimate only inside its own domain pack, forbidden in core.
  • Scripts and hooks read flavor from ${CLAUDE_PROJECT_DIR}/.claude/project.json at runtime; never hard-code paths or project names.
  • Prose examples use neutral placeholders (apps/<mainApp>, <device>, <envAlias>) or neutral example domains (orders/line-items).
  • Agent frontmatter identity is swarmery-core.
  • scripts/scan-flavor.sh is the ratchet: the count must stay at zero.

Graduation rule — flow goes UP only (docs/EXTENDING.md)

New components are born project-local (in a consumer's .claude/). When a second project needs one, promote it to a domain pack; when every project needs it, promote to core. Never copy framework files downward into projects. Promotion = de-flavor it → move into pack/core → bump that plugin's semver → delete the donor's local copy.

On a name collision, a consumer's project-local component overrides the plugin's — that's the intended override mechanism, not forking.

Template resolution

Agents look in ${CLAUDE_PROJECT_DIR}/.claude/templates/ first, then fall back to ${CLAUDE_PLUGIN_ROOT}/templates/. Generic templates ship with core; project-specific ones stay with the project.

Working rhythm

Keep going while the work is still yours to do. When a step does not need the operator, take it — a status note belongs in the same message as the next action, never in a message of its own. Stop and ask only when you genuinely cannot continue without the operator (an unresolved product decision, a missing credential, the same blocker surviving two honest attempts), or before anything destructive: deleting data, force-pushing, rewriting history, or changing something outside this repository.

"Keep going" moves you through the work, never through a gate. Commits, pushes, MRs, migrations and deploys stay the operator's call whenever they already were, and permission prompts stay on.

Close a run with these four headings, each written out even when the answer is "none":

  • Blocked on me — what needs the operator, and what it unblocks.
  • Changed — files touched, and why.
  • Found — what the work revealed that nobody asked about.
  • Unverified — what you could not confirm, and what would confirm it.

Self-hosting (dogfooding)

This repo is itself a swarmery consumer: .claude/ is a plain committed directory (no agents/ repo + symlink — that pattern exists only for multi-repo consumer workspaces sharing one overlay). settings.json enables core@swarmery from the GitHub marketplace like any consumer; project.json sets AGENT_PROJECT=swarmery (workspace: swarmery-workspace/swarmery/); the statusline runs straight from source at plugins/core/statusline/.

Installed plugins come from the cache (~/.claude/plugins/cache), so local edits to plugins/** are NOT what the session runs. To test in-progress plugin changes, load them live for one session:

claude --plugin-dir plugins/core                 # repeatable: --plugin-dir plugins/infra-pack …

scripts/sync-cache.sh rsyncs local plugins/** into the installed cache. The hook that calls it is versioned at scripts/git-hooks/post-commit — install once per clone with git config core.hooksPath scripts/git-hooks. The hook and the script each check on their own (so a stale copy of either can't bypass the other) that they run in the primary worktree on main: a linked worktree (daemon phase runs, plan runs, subagent worktrees) or any other branch refuses and exits 0, so unmerged plugin code never reaches the installed caches. Override a deliberate "test my branch live" run with SWARMERY_SYNC_CACHE_FORCE=1 (or --force on a manual script run); --plugin-dir remains the preferred way to test uncommitted or branch work live without touching any installed cache.

Never re-register the local checkout as a marketplace: marketplace.json name is swarmery, and a local-path registration would replace the GitHub source globally, breaking the /plugin update distribution path all consumers rely on.

Conventions

  • Conventional commits (feat:, refactor!:, chore:); semver bumps in plugin.json accompany plugin changes, with the marketplace metadata.version tracking the core version.
  • Every real agent routing bug or output-contract regression should become a promptfoo test case in evals/ (prefer contains/regex for hard contracts, llm-rubric for judgment calls).
  • Every PR against this repo fills .github/PULL_REQUEST_TEMPLATE.md in full — GitHub only pre-populates it for a same-repo PR; gh pr create from a fork needs --body-file pointed at that same template, filled in, not skipped. The Gates section takes pasted command output, not "should pass" — run the commands in the template (scripts/scan-flavor.sh, scripts/docgen/apply-counts.sh --check, scripts/docgen/check-coverage.sh, scripts/validate-agent-refs.sh, scripts/tests/*.test.sh, plus tools/swarmery's make build && make test when that tree is touched) and paste the real result for each.

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.