Progress Ledger

Keep a Magentic-style task and progress ledger.

Skill metadata

Source	Bundled (installed by default)
Path	skills/research/progress-ledger
Version	1.0.0
Author	VibeOS
License	MIT
Platforms	linux, macos, windows
Tags	research, orchestration, multi-agent, kanban, planning
Related skills	analysis-orchestration, professional-research, challenge-gate

Reference: full SKILL.md

信息

The following is the complete skill definition that VibeOS loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.

Progress Ledger Skill

Maintain a Task Ledger (facts, guesses, plan) and a Progress Ledger (current step, assignee, stall count, replan notes) for long jobs. Inspired by Magentic-One — without peer agent chat. Use files or a Kanban root-task comment; do not invent a new core tool.

When to Use

• Multi-step research, creative, or operate jobs longer than a few tool rounds.
• delegate_task batches or Kanban swarms where the parent must replan on stall.
• User asks to “track progress”, “don’t get stuck”, or “show the plan”.

Prerequisites

• Writable workdir (session cwd or Kanban workspace).
• Optional: Kanban board for durable jobs (vibeos kanban / kanban_* tools).
• Related: analysis-orchestration for gatherer/critic/synthesizer roles.

How to Run

1. Copy templates/ledger.md to the workdir as progress-ledger.md (or pin the same JSON block as a Kanban comment on the root task).
2. At job start: fill Task Ledger — known facts, open guesses, ordered plan.
3. Each major step: update Progress Ledger — current step, who owns it (role/profile), stall_count, last_progress_at, blockers.
4. If stall_count ≥ 2 with no new artifacts: replan (outer loop) — revise Task Ledger plan, reset stall, note what failed.
5. On finish: set status: done and point to final artifact paths.

Quick Reference

Field	Where	Purpose
facts	Task Ledger	Confirmed evidence
guesses	Task Ledger	Unverified hypotheses
plan	Task Ledger	Ordered steps
current_step	Progress Ledger	What is in flight
assignee	Progress Ledger	Role/profile owning the step
stall_count	Progress Ledger	Consecutive no-progress ticks
blockers	Progress Ledger	CAPTCHA, missing keys, waits

Template path (relative to this skill): templates/ledger.md.

Procedure

Outer loop (Task Ledger)

When starting or after a stall replan:

1. List facts you would bet money on (with source pointers).
2. List guesses separately — never mix into facts.
3. Write a short plan (5–12 steps). Prefer durable Kanban tasks for steps that must survive restart.

Inner loop (Progress Ledger)

After each child/delegate_task result or Kanban heartbeat window:

1. Ask: did we gain a new artifact, finding, or decision?
2. If yes → update current_step, reset stall_count to 0.
3. If no → increment stall_count; if ≥ 2, jump to outer-loop replan.
4. Record human gates (assignee: human, ChallengeGate) as blockers — do not thrash tools behind a wall.

Persistence choices

Job length	Store ledger in
Single chat turn / short batch	progress-ledger.md in workdir
Multi-hour / restart-safe	Kanban root task via CLI (below) + file copy
Cron / monitor	Job workdir file; optional archival memory later

Kanban persistence (CLI)

Upsert the ledger onto the root task (survives restart):

vibeos kanban ledger <root_task_id> --set progress-ledger.md
vibeos kanban ledger <root_task_id>            # print body
vibeos kanban ledger <root_task_id> --json     # machine-readable

Dashboard: GET/PUT /api/plugins/kanban/tasks/{id}/ledger.
Marker: <!-- vibeos:progress_ledger v1 --> (upsert keeps a single comment).

Promote process-local work → Kanban (manual)

Background delegate_task is process-local — it dies on app restart. When a job outlives a short batch (Fleet shows a promote hint after delegation.promote_hint_after_seconds, default 600s), manually create a durable task. Never auto-create Kanban rows without an explicit command.

# Flags
vibeos kanban from-delegation --title "Continue research" --goal "…" \
  --context "constraints…" --summary "partial findings…" \
  [--ledger-file progress-ledger.md] [--assignee profile] [--ready]

# Or JSON handoff file
vibeos kanban from-delegation --from-json handoff.json --json

Then keep updating the ledger on the new task id with vibeos kanban ledger.

Pitfalls

• Do not dump the full parent transcript into children — put decisions and constraints into the ledger / delegate_task context package.
• Do not treat peer agent chat as the ledger — comments drift; structured fields do not.
• Leaves cannot write memory; durable facts go to the ledger / Board KB / parent promotion paths.
• Avoid change-detector “progress” (rewriting the same paragraph) — require artifacts or verified findings.

Verification

• progress-ledger.md (or Kanban comment) exists with both ledger sections.
• After a deliberate stall, stall_count rises and a replan note appears.
• Final status is done or blocked with human-readable blockers.
• Fleet / user can open the ledger file without reading raw agent logs.