# Fulcra Agent Reconcile

> 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.

- **Type:** Skill
- **Install:** `agentstack add skill-ashfulcra-fulcra-tools-fulcra-agent-reconcile`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ashfulcra](https://agentstack.voostack.com/s/ashfulcra)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ashfulcra](https://github.com/ashfulcra)
- **Source:** https://github.com/ashfulcra/fulcra-tools/tree/main/skills/fulcra-agent-reconcile
- **Website:** https://fulcradynamics.com

## Install

```sh
agentstack add skill-ashfulcra-fulcra-tools-fulcra-agent-reconcile
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Fulcra Agent Reconcile

Enhances the [`fulcra-agent-teams`](https://github.com/fulcradynamics/agent-skills) skill. Bare teams
tracks tasks as OKF markdown under `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//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//_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)
```yaml
---
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: ash                      # for needs-me
owner: claude-code:host:web
blocked_on: null
due: null
not_before: null                   # hides from needs-me until this time
---

```
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//` — 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  ` brings one back; `coord-engine search   --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 ` | 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 ` | 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 ` (see [Usage](#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 /packages/coord-engine` — from the git tag or a checkout).
See [`references/reconcile-cli.md`](references/reconcile-cli.md).
```bash
coord-engine reconcile             # feed delta (or full-scan fallback) + heal views
coord-engine board    
coord-engine needs-me  --agent 
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ashfulcra](https://github.com/ashfulcra)
- **Source:** [ashfulcra/fulcra-tools](https://github.com/ashfulcra/fulcra-tools)
- **License:** MIT
- **Homepage:** https://fulcradynamics.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ashfulcra-fulcra-tools-fulcra-agent-reconcile
- Seller: https://agentstack.voostack.com/s/ashfulcra
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.