runs-index

Update run status fields in .runs/index.json for a given run_id.

5|Updated Nov 26, 2025
One-click install
npx skills add https://github.com/EffortlessMetrics/demo-swarm --skill runs-index
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: runs-index
Source: https://github.com/EffortlessMetrics/demo-swarm/tree/main/.claude/skills/runs-index
Command: npx skills add https://github.com/EffortlessMetrics/demo-swarm --skill runs-index

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill automates the structured tracking of development run statuses, eliminating the manual effort and inconsistencies associated with keeping project progress visible and auditable. It ensures your .runs/index.json is always current.

Core Features & Use Cases

  • Deterministic Index Updates: Safely updates status, last_flow, and updated_at fields within .runs/index.json for a given run_id.
  • Stable Diffs: Ensures consistent ordering and minimal changes to the index file, making version control clear and manageable.
  • Controlled Writes: Only modifies specific, designated fields, preserving other run metadata owned by other agents.
  • Use Case: At the conclusion of each SDLC flow (e.g., after "Signal cleanup"), automatically update the index.json to reflect the latest status (e.g., "VERIFIED") and the last completed flow for a specific run, providing real-time project visibility and audit trails.

Quick Start

Update the index.json for run 'feat-auth' to status 'VERIFIED' after the 'signal' flow, using the current timestamp generated by the 'time now' command.

Frequently Asked Questions about runs-index

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I automatically update run status in a JSON index file?

Run status updates are performed by upserting to `.runs/index.json`, modifying only `status`, `last_flow`, and `updated_at` fields for a given `run_id`. This automation eliminates manual tracking and keeps project progress visible and auditable throughout your SDLC workflows.

What does deterministic index updating mean for version control?

Deterministic updates ensure consistent field ordering and minimal file changes, producing stable diffs in version control. This makes it clear what changed in each run without noisy or unpredictable modifications to your index.

Can I update run metadata without overwriting other fields?

Yes. The tool modifies only designated fields—`status`, `last_flow`, and `updated_at`—while preserving other run metadata owned by other agents, ensuring controlled writes and preventing accidental data loss.

When should I call this tool in my project workflow?

Invoke it at the conclusion of SDLC flows, such as after cleanup or signal steps, to reflect the latest run status (e.g., 'VERIFIED') and last completed flow for real-time visibility and audit trails.

What file structure does this tool require?

The `.runs/index.json` file must exist before use. The tool requires repo-root relative paths and ensures idempotent updates, emitting 'ok' with exit code 0 on success or an error message with non-zero code on failure.

Does this tool create new fields or files?

No. It updates existing fields only and does not create new files or fields, maintaining a stable, predictable index structure aligned with your SDLC automation.