Fulcra Agent Tasks

Fulcra Agent Tasks

Enhances the fulcra-agent-teams skill. Bare teams tracks long-running work as freeform task/.md. This skill gives those docs a typed lifecycle — a real status/priority/assignee and a validated state machine — so a task's state is queryable (via fulcra-agent-reconcile) and can't take an illegal jump (e.g. done → active). Pairs with fulcra-agent-reconcile: this skill writes task state; reconcile reads/heals the views.

Where to start — the re-entrancy probes

Before creating or transitioning a task, probe engine health and what work is already waiting. Enter at the first probe that fails (per the repo's skill-quality pattern, docs/skill-quality-pattern.md); task writes are parse→modify→write and a same-status update is idempotent, so re-entry never corrupts state:

| 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 (see Usage / fulcra-agent-reconcile) — do NOT write tasks against a broken engine | | Aggregate fresh? | coord-engine status | output does NOT contain (no aggregate for team/ (the CLI's missing-aggregate hint) | run coord-engine reconcile to build the aggregate, then re-probe | | Work for me? | coord-engine needs-me --agent | prints 0 item(s) need : (a non-zero count means work is waiting — enter there) — read the rows (including any [REVIEW] pending verdict review-pending rows) before starting new work | pick up the listed items (transition them via task update/task done) before creating more |

All probes pass with nothing needing you → the engine is healthy, views are fresh, and your queue is clear; proceed to create or advance tasks below.

Why the writes go through the engine

Writing OKF frontmatter correctly and enforcing which transitions are legal are deterministic requirements — a malformed doc or an illegal waiting → done is a correctness bug, not a style choice. So the lifecycle commands are the shared coord-engine tool (parse→modify→write, transition-checked), not prose the agent hand-edits. Composing the human note in the task body is fine as prose; the structured state is not.

The state machine

proposed → active | waiting | abandoned | done
active   → waiting | blocked | done | abandoned
waiting  → active  | blocked | abandoned
blocked  → active  | waiting | abandoned
done, abandoned → (terminal)

done requires evidence. A same-status update is always allowed (idempotent edit).

Usage

Needs fulcra-api authenticated and coord-engine installed — standalone: uv tool install "git+https://github.com/ashfulcra/fulcra-tools.git@#subdirectory=packages/coord-engine" (any coord skill brings the same engine; installing once serves all).

# create a task doc at team//task/.md
coord-engine task start  "Fix the widget" \
    --workstream web --priority P1 --status proposed --assignee ash --summary "one-liner"

# move it through the machine (illegal transitions are rejected with a clear error)
coord-engine task update  fix-the-widget --status active --next "write the test"
coord-engine task block  fix-the-widget --blocked-on reviewer --unlock "review lands on PR #42"

# finish it — evidence is required
coord-engine task done  fix-the-widget --evidence "PR #42 merged"

Each write stamps timestamp and appends a dated note to the task body; the Fulcra File Store versions every write, so the full history is preserved. After changing tasks, run coord-engine reconcile to refresh the index and views (or let a scheduled reconcile do it).

See [references/tasks-cli.md](references/tasks-cli.md) for the full flag list and the OKF Task shape.

Source & license

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

• Author: ashfulcra
• Source: ashfulcra/fulcra-tools
• License: MIT
• Homepage: https://fulcradynamics.com

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