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

fulcra-agent-reconcile

Skill10 starsChanged 2 months agoMITView on GitHub

Give a fulcra-agent-teams space self-healing, queryable task views: fold changed OKF task docs from the data-updates feed, retain a fail-closed full-scan fallback, regenerate task/index.md and log.md, and answer status/board/needs-me/search in one read.

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is 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.

  • 1

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    After creating/updating tasks in a team space, to refresh the index and views.

    line 60
  2. Very specific:

    Before reconciling or querying, probe whether the engine is usable and whether the aggregate this skill owns is already fresh.

    line 82

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

Enhances the fulcra-agent-teams skill. Bare teams tracks tasks as OKF markdown under team/<team>/task/ and asks agents to hand-maintain task/index.md. At any real scale that index drifts. This skill makes the index engine-owned and self-healing and adds structured queries the convention otherwise lacks — without changing how tasks are written.

What it does

A bundled stdlib-only tool (coord-engine) that, for a given team:

  • Folds changed team/<team>/task/*.md docs from the authoritative data-updates feed, reading only the changed shards.
  • Heals task/index.md (OKF §6, grouped by status) and appends task/log.md (OKF §7, status transitions), with a periodic full-scan drift check that loudly rebuilds any divergence.
  • Emits team/<team>/_coord/summaries.json — a fast-path aggregate so reads are one download, not N. Alongside the task rows it builds two read-side projections: reviews (coord.reviews.projection.v1 — per-slug verdict state) and forge (coord.forge.projection.v1 — PR responsibility + feedback item ids), which briefing/needs-me serve instead of scanning hundreds of raw shards per wake. The projection build is budgeted (COORD_PROJECTION_BUILD_BUDGET, default 240s) and converges across passes on a large legacy corpus; an incomplete build is marked and left unserved rather than served as current.
  • Answers status / board / needs-me / search from that aggregate.

Properties: orphan-proof (scheduled full-scan drift checks rebuild from ground truth), incremental (a durable feed cursor reads only changed task shards), degraded-safe (any feed/cursor/shard doubt falls back to the full listing scan; if that scan fails, the pass aborts and leaves the prior index intact — never publishes a truncated view).

The OKF Task contract (what a task doc looks like)

---
type: Task                         # OKF required
title: Fix the widget             # OKF display name
description: one-line summary       # OKF — becomes the index bullet text
timestamp: 2026-07-01T14:00:00Z    # OKF last-change time
tags: [workstream:web, kind:bug]
# coord extensions (OKF-legal producer keys):
status: active                     # proposed|active|waiting|blocked|done|abandoned
priority: P1                       # P0|P1|P2|P3
assignee: user                      # for needs-me
owner: claude-code:host:web
blocked_on: null
due: null
not_before: null                   # hides from needs-me until this time
---
<body: human notes>

Bare-teams tasks that lack the extension keys are still first-class — missing status/priority are backfilled (proposed/P2).

When to use

  • After creating/updating tasks in a team space, to refresh the index and views.
  • On a schedule (a heartbeat) to keep a busy team's index healed.
  • Whenever you want to query a team's work (status/board/needs-me/search) instead of reading files.

Ownership rule

Once you use this skill, task/index.md and task/log.md are engine-owned — let the tool regenerate them; edit task content docs, not the indexes. _coord/summaries.json is a cache — deleting it is safe, but re-running does not always reproduce it in ONE pass: the review/forge projection sections are budget-bounded and converge over several passes on a large corpus (until then the folds say raw scan — reviews projection incomplete (scanned N/M) and answer correctly the slow way). Recoverable archival is move-not-delete (Fulcra file delete isn't CLI-undoable).

Retention (optional add-on)

With --retention-days N (or env COORD_RETENTION_DAYS), reconcile archives terminal tasks older than N days to task/archive/<YYYY-MM>/ — a verified move (copy → read-back → delete), never a bare delete — and moves the task's ack/response shards with it. Once per day, capped per pass. coord-engine task restore <team> <slug> brings one back; coord-engine search <team> <q> --archived searches the cold archive. Retention defaults to 14 days; set COORD_RETENTION_DAYS=0 or pass --retention-days 0 to disable it explicitly.

Where to start — the re-entrancy probes

Before reconciling or querying, probe whether the engine is usable and whether the aggregate this skill owns is already fresh. Enter at the first probe that fails (per the repo's skill-quality pattern, docs/skill-quality-pattern.md); reconcile is the healer — a full rebuild from ground truth, orphan-proof and degraded-safe — so re-running it never corrupts state and 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 — a ✗ line names the broken leg (launcher not on PATH, or File Store unreachable → fulcra auth login); do NOT reconcile against a broken engine
Aggregate present + fresh?coord-engine status <team>output does NOT contain (no aggregate for team/ (the CLI's missing-aggregate hint, printed only when no aggregate has been built)Reconcile — run coord-engine reconcile <team> (see Usage) to fold feed changes or take the fail-closed full scan and build/heal the aggregate, then re-probe

Both probes pass → the engine is healthy and the aggregate exists, so status/board/needs-me/search read the fresh view; reconcile again on your cadence (or heartbeat) to keep it healed as tasks change.

Usage

This skill drives the shared coord-engine tool — invoked as the bare installed binary (never uv tool run, which resolves an ephemeral version; coord-engine is not on PyPI), so the skill itself stays pure prose + references (no bundled code). Needs fulcra-api authenticated and coord-engine installed (uv tool install <fulcra-tools>/packages/coord-engine — from the git tag or a checkout). See references/reconcile-cli.md.

coord-engine reconcile <team>            # feed delta (or full-scan fallback) + heal views
coord-engine board    <team>
coord-engine needs-me <team> --agent <id>

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.