fulcra-tools: Instructions file for Claude Code

Fulcra Tools — agent guide

Your entry point to this repo. Fulcra helps agents know their user, know what's happening in their user's world, work with their user's other agents, and become more helpful over time — the packages here are working examples of all four. This file covers the non-obvious environment and the conventions you can't infer from the source; the README.md tells the top-level story (what each package is, how to install the pieces) and this file does not repeat it.

Keep the monorepo framing. These are unofficial, unsupported tools and skills vibe-coded by Fulcra's lawyer to work with Fulcra. Coordination and continuity work independently of Collect. Collect is an optional host for local/source connectors, not a prerequisite for using Fulcra. The root README indexes every package and bundled skill; retain the human introduction and verify release claims.

Record each new actionable user request as an owned bus task, or update the matching task. Keep its scope, status, prerequisites, next action, and completion evidence current. A continuity checkpoint is not a substitute for the task backlog.

Coord V5 has an opt-in parallel transport read-updates route. Use shadow mode before gated deployment; update watermarks are not record cursors or complete-history proof. Quiet hints never cancel retained delivery obligations. Preserve the direct route, private journals and per-source scope; see the package README for audit/fallback limits.

README updates are required with every change. Every update to Fulcra Tools or anything in it must update the relevant READMEs in the same PR, including fixes, plugins, installers, commands, and workflows. If a package has no README, update its nearest owning README or add one. Update the root README when the change affects installation, available tools, or release status. Document current behavior and limits; label unfinished work. Reviewers must block a change whose README update is missing or stale. This is a standing repository rule.

This file is a ship-gate artifact. Every PR that changes agent-facing behavior — CLI verbs, skills, conventions, environment requirements, review rules — MUST update this file in the same PR. Reviewers: treat a stale AGENTS.md as a blocking finding. If your change doesn't alter what an agent needs to know, say so in the PR body ("AGENTS.md: no change needed").

No one-off fixes on coordination or continuity surfaces (operator law, 2026-08-14; earned by twelve strict-consumer incidents, OUTPUT-CONTRACT.md). Root-cause every incident and fix it upstream at the surface that produced it, not with a defensive patch at the consumer. The models reading these surfaces are smart; what they need from us is surfaces that are durable.

Apple Notes reconciliation/writeback: listing timestamps are not a content baseline. Reconciliation reads tracked vault bodies so edits near a sync are not missed; retain the complete internal change list and cap only report presentation. Partial AppleScript write failures must produce a failed report and failed run.

Selected-list task sync: Reminders uses EventKit, with separate read-only permission checks and explicit permission requests. No lists are selected by default. Import and source completion must re-check live selection, enabled state, and preview mode before each write. Task status is open or resolved; identity and generation fields bind a completion to the source task. Normalize task paths to absolute Fulcra paths at the Files adapter boundary for both history lookup and upload; the API rejects relative upload paths. Read all unseen Fulcra file versions so a concurrent bot edit survives an importer write. Missing source tasks are never completion evidence. Todoist task-detail lookup can return checked: true after completion; accept it only with valid explicit completion evidence. Keep active-list validation separate: a checked task there still invalidates the snapshot. Recurring writeback is unsupported until the provider can atomically protect the intended occurrence. Capture RunContext.config_epoch with settings and pass it into the task engine; check it in the live selection callback. Configuration and credential transitions must invalidate pending journals even when no sync runs between the changes. Save configuration under a cross-process lock and publish it atomically. Merge each caller's edits against its immutable load/save baseline: enabled membership, interval keys, and individual plugin-setting keys merge independently. An unchanged stale value must never undo a disable or remove another caller's setting. Divergent edits to the same field raise ConfigConflictError before publication; reload and retry instead of force-saving the stale object. For explicit user submissions use enable, disable, set_interval, and update_plugin_settings(plugin_id, values): these preserve intent even when the submitted value equals the loaded baseline. Direct mapping edits carry only semantic differences and cannot represent an explicit unchanged-value request. Interactive Fulcra sign-in/sign-out must persist an account_transition gate and rotate all plugin epochs before changing the token, then rotate again before clearing the gate on success. Task callbacks reject the gate as well as stale epochs. Failure leaves the gate closed until an interactive retry succeeds; normal configuration saves and automatic token refresh must never clear it.