AGENTS.md - SyncytiumMD

Universal agent instructions generated by SyncytiumMD. Source of truth: .syncytium/.

🤝 Live Handoff Status

• Active Agent: opencode (Next: Human)
• Status: BLOCKED
• Current Goal: v0.3.1 npm publish and MCP Registry listing are blocked on npm OIDC trusted-publisher setup
• Pending Tasks:
  • On npmjs.com add a Trusted Publisher for syncytium-md: GitHub Actions, owner mrcbrbn5361, repo SyncytiumMD, workflow release.yml
  • Re-run Release run 42053623967, then run the MCP Discovery workflow (or re-run 42053623576)
  • Rotate any credential that was pasted into chat earlier
• Recently Touched:
  • .gitattributes
  • src/core/storage.ts
  • server.json
  • src/mcp/safety.ts
  • .github/workflows/release.yml
  • .github/dependabot.yml
  • scripts/build-discovery.mjs
  • .github/workflows/discoverability.yml
• Notes: No npm credential exists locally or in GitHub secrets, so 0.3.1 cannot be published until the npm-side trusted publisher exists. After that, both workflows are idempotent and need no secrets.
• Last Updated: 2026-11-05T15:24:48.885Z

System Architecture

System Architecture & Technology Stack

Single source of truth for every AI agent working on this repository. Every bridge file (CLAUDE.md, AGENTS.md, .cursor/rules/*.mdc, …) is generated from this directory by syncytium sync — never edit those by hand.

Overview

SyncytiumMD is a CLI + library + MCP server that maintains one canonical context (.syncytium/) and transpiles it into the native instruction format of every AI coding tool in use. It also provides multi-agent coordination: a lease-based workspace lock, a handoff baton with an audit trail, and a local visual knowledge graph.

Technology Stack

• Runtime: Node.js 20+ (ESM, build-first; tests run from dist-tests/)
• Language: TypeScript, strict plus noUnusedLocals, noUnusedParameters, noImplicitOverride, noImplicitReturns, verbatimModuleSyntax
• Build: tsup (esbuild) with dts: true → dist/{index,cli/index,mcp/index}.js
• CLI: Commander.js + picocolors
• Validation: zod (config schema, rule frontmatter, ADR, every MCP tool input)
• Parsing: gray-matter (frontmatter) — all loaders deep-copy, see ADR-006
• Watching: chokidar
• MCP: @modelcontextprotocol/sdk over stdio
• UI: zero-dependency node:http server + a single-page Three.js app (Three.js r128 loaded from cdnjs; the vault/doc panels degrade gracefully without it)

Module Map

Engine API

init · sync · diff · doctor · lint · validate · handoff · getHandoffHistory · addDecision · removeDecision · listDecisions · addRule · getRule · removeRule · listRules · exportBundle · clean · importExisting · getStatus · listTrash · restoreFromTrash · acquireLock · releaseLock · renewLock · getLockStatus · installGitHook · uninstallGitHook · installCiWorkflow · uninstallCiWorkflow · detectStack · getKnowledgeGraph · startUiServer · watch

Data Flow

.syncytium/  ──load──►  CanonicalContext  ──generate──►  GeneratedFile[]  ──write──►  bridge files
     ▲                                                                                        │
     └────────────────────  diff / prune / preserve user sections  ◄────────────────────────┘

sync writes every generated file, then prunes banner-tagged files that no rule produces any more. diff compares content and reports identical, modified (with a unified patch), missing_on_disk, and unmanaged (orphans).

MCP Safety Model

Every advertised tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) from src/mcp/safety.ts, and the server enforces a per-tool sliding-window call budget in the same module. Destructive tools (remove_rule, remove_decision) default to dryRun: true; an actual delete needs dryRun: false and confirm: true. Before deleting, the engine archives the exact rule/ADR bytes under .syncytium/memory/trash/, and syncytium_restore (plus listTrash/restoreFromTrash in the library) can undo the operation. doctor is read-only: it reports remediation strings but never executes them.

The contract is mechanical, not descriptive: every inputSchema is closed with additionalProperties: false and documents each property, and every stable read tool declares an outputSchema plus matching structuredContent. Mutation is never hidden behind a read annotation — validate is read-only and the separate validate_fix tool performs repairs.

Discovery

server.json describes the npm package to registry.modelcontextprotocol.io, and mcpName in package.json proves npm ownership. .github/workflows/discoverability.yml regenerates llms.txt / llms-full.txt, validates the manifest, and publishes it with GitHub OIDC; no credential is stored in the repository.

Directory Layout

• src/ — source code and adapters
• tests/syncytium.test.ts — 123 tests, build-first (npm run build && tsc -p tsconfig.tests.json && node --test dist-tests/*.test.js)
• scripts/release.mjs — verify → publish → CDN-poll → global install
• .syncytium/ — single source of truth
  • rules/ — canonical, stack-aware rules
  • memory/decisions.md — ADRs
  • memory/handoff-history.json — baton audit trail
  • memory/lock.json — machine-local lease (git-ignored)
  • HANDOFF.md — live agent state

Engineering Guidelines

📌 AI Tool Adapter Guidelines & Architecture

Standards for implementing new IDE and CLI bridge adapters in SyncytiumMD

AI Tool Adapter Guidelines

When adding or updating adapters in src/adapters/:

1. Interface Contract:
   • Every adapter must implement AgentAdapter from src/core/types.ts.
   • Implement readonly id, readonly name, readonly category, readonly description, readonly defaultTargetFiles.
2. Deterministic Output:
   • The generate(context: CanonicalContext) method must return an array of GeneratedFile[].
   • Every file must include a leading or trailing SyncytiumMD header comment (e.g. # Auto-generated by SyncytiumMD) unless the format forbids comments.
3. Preserve User Modifications:
   • Adapters should respect user custom sections where supported.
4. Registration:
   • Register all new adapters in AdapterRegistry (src/adapters/registry.ts).
5. Coverage:
   • Add unit tests verifying target file generation in tests/syncytium.test.ts.

📌 Code Style & Formatting

Enforce clean, readable, modern standards across the project

Code Style & Formatting

• Write clean, modular, and self-documenting code.
• Always prefer strict types, immutable data structures, and pure functions where reasonable.
• Keep functions concise with a single responsibility.
• Preserve existing comments and documentation unless explicitly asked to modify them.
• Avoid unnecessary dependencies; prefer standard library APIs where possible.

Repository-specific conventions

• Comments explain why. A comment restating what the code does is noise; a comment explaining a non-obvious constraint, a bug workaround, or a deliberate deviation is mandatory. Prefer a short comment at the point of the decision over a long block at the top of the file.
• Never let a shared, cached object escape. gray-matter hands back the same object for identical content, and DEFAULT_CONFIG / INITIAL_RULES / INITIAL_DECISIONS are module-level singletons. Copy before mutating (see clone() in src/core/storage.ts and deepClone() in the config path).
• Order-dependent output is a bug. Rule loading is sorted explicitly so generated files are byte-identical across platforms.
• Derive, do not duplicate. The version lives in src/version.ts, the Markdown renderer in src/ui/markdown.ts (injected into the browser bundle via Function.prototype.toString()), and path safety in src/core/paths.ts. A second copy will drift.
• When a bug is fixed, add a test that fails without the change and name the regression in the test description.

📌 Release & Verification Criteria

Every change ships green: typecheck, build, tests, lint, and zero context drift

Release Criteria

A change is not done until all of these pass locally:

npm run typecheck   # tsc --noEmit over src/ and tests/
npm run build       # tsup, ESM + .d.ts
npm test            # 129 tests, build-first + dist-tests (Node 20+)
npm run verify      # all three, in order

Before opening a PR

• node dist/cli/index.js lint — canonical rules and frontmatter are valid.
• node dist/cli/index.js diff — no drift between .syncytium/ and the committed bridge files. Commit the regenerated files together with the change.
• node dist/cli/index.js doctor — no error checks. Warnings are acceptable only when they are pre-existing and unrelated.

Releasing

npm run release runs the whole pipeline and fails loudly:

1. typecheck → build → test
2. npm publish
3. polls npm view with exponential backoff until the version is served
4. npm install -g and verifies the installed version

Never hand-edit src/version.ts or package.json version independently: a unit test asserts they match, and --bump updates both together.

Definition of done

• New behaviour has a test that fails without the change.
• Public behaviour changes are reflected in README.md and README.tr.md.
• Architectural decisions go into .syncytium/memory/decisions.md via syncytium adr add.
• The handoff baton is updated before the turn ends: syncytium handoff --from "<agent>" -g "<goal>" -d "<done>" -t "<todo>".

📌 Security & Safe Coding

Security rules, secrets handling, and sanitization

Security & Boundaries

• The Obsidian Studio server binds to 127.0.0.1 and rejects any request whose Host header is not a loopback name. This is a DNS-rebinding guard: without it, any web page the user has open could read /api/file from their workspace. --allow-remote lifts the guard and must only be used knowingly.
• Access-Control-Allow-Origin is null (same-origin) by default.
• /api/file refuses in-root secrets (.env*, *.pem, *.key, id_rsa, .npmrc, .netrc, …) and everything under .git/, in addition to the path-traversal containment check.
• Rule ids arrive from user-authored frontmatter and are interpolated into generated file paths. Every path is slugified (src/core/paths.ts) and every write is re-checked against the workspace root before touching disk.
• The UI escapes projectName and all node ids, serialises its bootstrap config with </>/&/U+2028 escaped, and uses event delegation instead of inline onclick — a hostile rule id in a cloned repo must not be able to run script.
• syncytium clean deletes only files carrying the Syncytium banner. A user's own .cursor/rules/my-rule.mdc is never touched.
• MCP tool inputs are validated with zod before they reach the engine.
• Every MCP tool declares honest readOnlyHint / destructiveHint / idempotentHint / openWorldHint annotations in src/mcp/safety.ts, and the server enforces a per-tool sliding-window rate limit there. A scanner or gateway can therefore reason about the surface, and a runaway agent loop is stopped in-process even when the client ignores the hints.
• Destructive MCP tools are safe by default: dryRun defaults to true and an actual delete requires dryRun: false and confirm: true.
• Deletions are recoverable. removeRule / removeDecision archive the exact source bytes under .syncytium/memory/trash/ before touching the live file, and syncytium_restore / restoreFromTrash undo the operation.
• syncytium_doctor is strictly read-only. Its fix strings are suggestions; it never runs them, spawns processes, or edits git/CI state.
• Never log or echo secrets, tokens or full file contents to stdout: stdout is the MCP JSON-RPC transport.

📌 Testing Standards & Verification

Quality assurance and test verification guidelines

Target Files: **/*.test.ts, **/*.test.tsx, **/*.spec.ts, tests/**/*

Testing Guidelines

• Write unit tests for all business logic and edge cases.
• Mock external network requests, timers, and heavy I/O in unit test suites.
• Verify tests pass before completing any implementation task.
• Follow the Arrange-Act-Assert pattern for test clarity.

🧠 Key Decisions (ADR)

• [ADR-001] Adopt SyncytiumMD as Universal Context Bridge: Use SyncytiumMD as the single source of truth (.syncytium/) to transpile and synchronize rules, memories, and handoff state across all AI coding tools. (accepted, 2026-09-19)
• [ADR-002] Zero-Heavy-Dependencies Knowledge Graph UI: Implement an embedded Canvas-based force-directed graph server using native node:http and Server-Sent Events (SSE). (accepted, 2026-09-19)
• [ADR-003] Lease-Based Multi-Agent Collision Prevention Lock: Introduce syncytium lock with time-expiring leases (e.g. 30-45 minutes) stored in .syncytium/memory/lock.json. (accepted, 2026-09-19)
• [ADR-004] Automated Release Pipeline with NPM CDN Replication Polling: Implement scripts/release.mjs (npm run release) which verifies tests, publishes, polls npm view with exponential backoff until live, and then installs globally. (accepted, 2026-09-19)
• [ADR-005] High-Performance 3D Knowledge Galaxy with Physics Sleep & Geometry Pooling: Implement Three.js unit sphere geometry and material caching/pooling, simulation alpha decay with auto-sleeping (0% idle CPU load), LOD lazy text sprite generation, floating hover tooltips, and compact view mode (--compact, --no-files, --no-tags). (accepted, 2026-09-19)
• …and 10 more in .syncytium/memory/decisions.md

Working Agreement

1. Read .syncytium/HANDOFF.md before starting work; it holds the live goal and pending tasks.
2. Acquire the lease with syncytium lock acquire --agent "<name>"; release it before you finish.
3. After finishing, run syncytium handoff --from "<name>" -g "<goal>" -d "<done>" -t "<todo>".
4. Never hand-edit generated files - change .syncytium/ and run syncytium sync.

Graphify code intelligence (active)

The vi3ecode-graphify MCP server serves this project's code graph: modules, dependencies, communities, and PR impact. Tools: query_graph, get_node, get_neighbors, get_community, shortest_path, god_nodes, graph_stats, list_prs, get_pr_impact, triage_prs. If your harness defers or hides MCP tools, load them first (tool search for "graphify") instead of assuming they are missing.

Make the graph your first investigation step, not a fallback:

• Before any repo-wide text search (grep/glob over unknown files), run query_graph on the symbol or path, then get_neighbors for its callers and dependents.
• Before editing a module others may import — including while fixing a failing test or reviewing a diff — check get_neighbors to scope the blast radius; use get_pr_impact or triage_prs for branch/PR-level work.
• For architecture, ownership, or "where does X live" questions, start from query_graph, get_community, god_nodes, or graph_stats.

Treat graph results as a map: verify the relevant source files before editing because source code remains authoritative. Skip the graph only when the task already names the exact files and nothing else depends on the lines you change. If you finish a multi-file task without a single Graphify query, state in one line why the graph was not needed. If the server is unavailable or stale, continue from source and say so. Never run Graphify build or update commands yourself; Vi3ecode owns graph maintenance.