name: pulseflow description: Maintain a Markdown task dashboard backed by agent-written append-only AI work logs, then sync a daily AI DONE TODAY section plus a weekly usage panel via heartbeat or on-demand refresh. Use when building or operating a reusable task system where: (1) human tasks live in a single NOW.md dashboard, (2) agents automatically append work records after each completed work unit, (3) heartbeat scans logs and refreshes the AI-derived sections, (4) a new workspace or vault needs initialization with templates, paths, and sync state.

PulseFlow

Build and operate a simple task system with one human-facing dashboard file and one append-only AI log flow.

Core model

Use one current dashboard file as the source of truth for active work.

• Weekly usage lives in one top summary panel only: AI USAGE THIS WEEK
• Human work lives in four sections only: FOCUS, TODAY, UP NEXT, DONE
• AI work lives in one summary section only: AI DONE TODAY
• Agents do not write the dashboard directly
• Agents append one log line after each completed work unit
• Heartbeat or an explicit refresh reads usage data plus logs and rewrites the AI-derived sections

File roles

Use these files and keep their roles strict:

• todo/NOW.md — current dashboard
• todo/history/YYYY-MM.md — monthly archive
• todo/system/config.json — installation-specific paths and agent list
• todo/system/sync-state.json — last processed offsets/checkpoints
• reports/<agent>-ai-log-YYYY-MM-DD.jsonl — append-only per-agent daily work logs

Initialization workflow

When setting up a new installation:

1. Create todo/, todo/history/, and todo/system/
2. Create todo/NOW.md from the dashboard template in references/now-template.md
3. Create todo/history/<current-month>.md from references/history-template.md if missing
4. Create todo/system/config.json from references/config-template.json
5. Create todo/system/sync-state.json from references/sync-state-template.json
6. Fill installation-specific values:
   • dashboard path
   • history directory
   • reports directory per agent
   • optional agentsFilePath per agent
   • enabled agent list
   • timezone
7. If an older dashboard exists, migrate the human task sections into the new todo/NOW.md
8. Do not import old AI activity retroactively unless explicitly requested
9. Create today's empty AI log files for enabled agents
10. Install or refresh managed AI logging rules in configured AGENTS.md files
11. If the installation explicitly wants scheduled summaries, fill notifications.summaryCrons in config and run scripts/install_summary_crons.js

Agent write contract

Each agent must append one JSON object per completed work unit to its own daily JSONL log.

Required fields:

• ts — ISO timestamp with timezone
• agent — agent name
• task — one-line work summary
• tokens — optional integer token count for that work unit; may be 0 or omitted

Example line: