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.
In this repository20 other files it gives its agents.
- AGENTS.mdAGENTS.md
- coordinator-disciplineSkill
- fulcra-agent-atcSkill
- fulcra-agent-automationSkill
- fulcra-agent-cloud-coordinatorSkill
- fulcra-agent-continuitySkill
- fulcra-agent-directivesSkill
- fulcra-agent-durable-stateSkill
- fulcra-agent-forgeSkill
- fulcra-agent-healthSkill
- fulcra-agent-operatorSkill
- fulcra-agent-presenceSkill
- fulcra-agent-reviewSkill
- fulcra-agent-rolesSkill
- fulcra-agent-tasksSkill
- fulcra-content-reviewSkill
- fulcra-fdeSkill
- fulcra-lab-resultsSkill
- map-our-teamSkill
- sealed-secretsSkill
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
- Distinctive: line 60
After creating/updating tasks in a team space, to refresh the index and views.
- Very specific: line 82
Before reconciling or querying, probe whether the engine is usable and whether the aggregate this skill owns is already fresh.
≈ “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.
Files
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/*.mddocs from the authoritativedata-updatesfeed, reading only the changed shards. - Heals
task/index.md(OKF §6, grouped by status) and appendstask/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) andforge(coord.forge.projection.v1— PR responsibility + feedback item ids), whichbriefing/needs-meserve 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/searchfrom 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) | Command | Passes when | If it fails, enter at |
| Engine + auth usable? | coord-engine doctor <team> | exits 0 and the last line is exactly doctor: healthy | fix 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>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
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.

