agentleFS
ashfulcraashfulcra/fulcra-tools/skills/fulcra-agent-directives/SKILL.md

fulcra-agent-directives

Skill10 starsChanged 2 months agoMITView on GitHub

Directed work for a fulcra-agent-teams space: tell an agent (or broadcast to all), schedule reminders, capture backlog, hand off with a checkpoint, and track a per-agent inbox with acks and re-notify — all deterministic.

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

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

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

    All verbs below run as coord-engine <verb> …:

    line 37

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill 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
SKILL.md

Fulcra Agent Directives

Enhances fulcra-agent-teams. Teams' native inbox is a drop-zone of markdown files; this skill adds structured directed work: a directive IS a task with an assignee, so it shows up in the reconcile views, carries priority + status machine, and has a deterministic per-agent inbox with acks (acking hides an item for you and stops re-notify) — without replacing the teams inbox for freeform messages.

Where to start — the re-entrancy probes

On waking (or before directing more work), probe your own inbox — what is already assigned to you and unacked. Enter at the first probe that fails (per the repo's skill-quality pattern, docs/skill-quality-pattern.md); reading the inbox is a pure fold and an ack is an idempotent single-file write (acking an already-acked slug just rewrites the same shard), so re-entry is always safe:

Probe (run in order)CommandPasses whenIf it fails, enter at
Engine + auth usable?coord-engine doctor <team>exits 0 and the last line is exactly doctor: healthyfix engine/auth first (see fulcra-agent-reconcile) — do NOT direct/ack against a broken engine
Inbox clear for me?coord-engine inbox <team> -a <id>the header line ends 0 item(s) (the fold found nothing open + unacked for you) — NON-mutating readWork your inbox — the header names a non-zero count and each following line is an open directive; act on / ack it (inbox <team> --agent <id> --ack <slug>) via Verbs before directing new work

Inbox clear → nothing is assigned to you and unacked; proceed to tell / broadcast / remind others, or capture backlog with later. Add --all only for audit/debugging: it restores acknowledged, closed, future, and @backlog history.

Verbs

All verbs below run as coord-engine <verb> …:

tell      <team> <assignee> <title> [-p P0..P3] [-s summary] [-n next] [--from me]   # direct work
broadcast <team> <title> …                        # assignee '*' — reaches every non-stale agent
remind    <team> <assignee> <when> <title> …      # hidden until WHEN (ISO or 5d/36h/10m)
later     <team> <title> …                        # backlog (@backlog; inbox --all surfaces it)
intent    <team> "<text>" --for user [--by <when>]  # capture a spoken commitment (intent:user item)
inbox     <team> [--agent X] [--json]             # actionable directives for X
inbox     <team> --agent X --all [--json]          # full directed history
inbox     <team> --agent X --ack <slug>           # ack: hides it for X, stops re-notify
respond   <team> <slug> --outcome TEXT [-e evidence]   # record a response + close the loop
threads   <team> --for <principal> [--json]       # FOLD: dropped work-in-progress for a principal

threads is a read-only fold, not a directive — it surfaces started-then-silent / blocked-on-principal / intent-never-started items the intent-capture doctrine leans on. Flags, modes, windows, and the threads-degraded row: see the CLI reference.

How the deterministic parts work

  • Inbox fold (engine): open tasks assigned to you or *, minus your acks (_coord/acks/<slug>/<agent-key>.md, one file per agent — collision-safe key), gated on not_before, priority-sorted. needs-me and briefing apply the same satisfaction rule, so an acknowledged directive cannot linger in one queue after leaving another. Served O(1) from the reconcile aggregate (acked_by is folded in at reconcile time; freshness is bounded by the reconcile cadence).
  • Broadcast completion: with fulcra-agent-presence installed, a * directive is complete when every non-stale roster agent has acked. Without presence, acking still hides per-agent (documented degradation).
  • Re-notify: unacked P0/P1 directives keep surfacing (inbox top, digest) until acked — an ack is a deliberate act; a mis-fired ack permanently silences that item for you.
  • Handoff is atomic: the checkpoint ref and the new assignee land in ONE task-file write, so there is no window where the work moved but the resume state doesn't exist.
  • intent — the spoken-commitment member of this family, with the capture doctrine. When the operator states an intent to ANY agent ("later today", "I'll enumerate that list"), that agent files it in the SAME turn with intent — an uncaptured commitment is the drop nobody can see; the coord-engine threads <team> --for user fold (dropped work-in-progress) only surfaces what was recorded. intent writes an ordinary directive (intent:user tag + assignee
    • intent_by window) through the same hash-slug delivery + read-back as tell, with ONE deliberate identity deviation: identity is text + assignee only — --by is NOT part of the slug. So restatement is well-defined and never forks a second item:
    • identical (same text, no --by or the same window) → pure dedup, rc 0 intent already captured;
    • new --by → the SAME commitment with a revised deadline → a verified in-place window update on the existing doc (rewrite intent_by → read-back-confirm the new window landed; unverifiable → rc 1, retry, never a silently-stale deadline);
    • a relative --by (5d/36h/10m) re-resolves from now on each restatement, so re-stating "by end of day" pushes the window forward rather than pinning the first resolution.
  • Shard-GC: reconcile prunes ack shards whose task no longer exists (orphan-proofing the ack dir).

Fail-closed notes

  • respond resolves the directive first: a name that maps to no directive doc (a display title instead of the hash-suffixed slug, or an unreadable read) fails rc-1 and records nothing — no ghost shard under a slug nobody owns while the real directive stays open. A resolved directive records the response shard, then closes the task (done, evidence = outcome); if the close is an illegal transition the response is still recorded and the failure reported.
  • A remind with an unparseable WHEN errors — it never creates a directive that fires at the wrong time.

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.