The Runs Index skill is a specialized automation tool designed for deterministic updates to the .runs/index.json file. It enables Claude agents to manage the lifecycle of automated tasks by precisely updating status, flow, and timestamps. By ensuring stable git diffs and idempotent operations, this skill provides a reliable way to track execution metadata within agentic CI/CD pipelines and developer workflows.

When should I use runs-index?

runs-index is useful in the following scenarios: • Automated Status Tracking: Update the execution status of specific runs (e.g., 'VERIFIED', 'FAILED') in a centralized index file after agent tasks are completed. • Pipeline Cleanup Management: Record the final state and 'last_flow' of a process in cleanup agents to ensure the repository's run history remains accurate. • Stable Metadata Versioning: Maintain a sorted and deterministic JSON index of repository runs, preventing merge conflicts and ensuring clean version control history during automated updates. • Idempotent Workflow Updates: Ensure that repeated status updates with the same parameters produce consistent results without corrupting the underlying data structure.

name	runs-index
description	"Update index.json status. Use for: upsert index.json, update status/last_flow/updated_at. Deterministic writes - stable diffs, no creation. Use only in run-prep and *-cleanup agents. Invoke via bash .claude/scripts/demoswarm.sh index upsert-status."
allowed-tools	Bash, Read, Write

Runs Index Skill

Deterministic updates to .runs/index.json. Write-bearing but with minimal surface.

Invocation

Always invoke via the shim:

bash .claude/scripts/demoswarm.sh index upsert-status [options]

Do not set PATH or call helpers directly. The shim handles resolution.

Operating Invariants

Repo root only

Assume working directory is repo root.
All paths are repo-root-relative.

Minimal ownership

This skill only updates:

status
last_flow
updated_at

Other fields (canonical_key, issue_number, pr_number, etc.) are owned by run-prep, signal-run-prep, and gh-issue-manager.

Stable diffs

Upsert by run_id (update in place, not append)
Preserve existing ordering
Output is sorted for stable git diffs

Allowed Users

Only these agents may use this skill:

run-prep
signal-run-prep
signal-cleanup
plan-cleanup
build-cleanup
gate-cleanup
deploy-cleanup
wisdom-cleanup

Command Reference

Command	Purpose
`index upsert-status`	Update run status in index.json

Quick Example

# Update index after signal cleanup
bash .claude/scripts/demoswarm.sh index upsert-status \
  --index ".runs/index.json" \
  --run-id "feat-auth" \
  --status "VERIFIED" \
  --last-flow "signal" \
  --updated-at "$(bash .claude/scripts/demoswarm.sh time now)"
# stdout: ok

Contract Rules

stdout: ok on success, error message on failure
exit code: 0 on success, non-zero on failure
Idempotent: Running twice with same args produces same result
No creation: If .runs/index.json doesn't exist, fail (run-prep owns creation)

Index Schema Reference

{
  "version": 1,
  "runs": [
    {
      "run_id": "feat-auth",
      "canonical_key": "gh-456",
      "task_key": "feat-auth",
      "task_title": "Add OAuth2 login",
      "issue_number": 456,
      "pr_number": null,
      "updated_at": "2025-12-11T22:15:00Z",
      "status": "VERIFIED",
      "last_flow": "signal"
    }
  ]
}

This skill only updates: status, last_flow, updated_at.

For Agent Authors

In cleanup agents:

Use runs-index for index updates (no inline jq)
Handle missing index — if .runs/index.json is missing, add a blocker and do not create it
Use runs-derive for reading — this skill is write-only

Example pattern in cleanup agent:

# Get current timestamp
TIMESTAMP=$(bash .claude/scripts/demoswarm.sh time now)

# Update index
bash .claude/scripts/demoswarm.sh index upsert-status \
  --index ".runs/index.json" \
  --run-id "$RUN_ID" \
  --status "$STATUS" \
  --last-flow "signal" \
  --updated-at "$TIMESTAMP"

Installation

The Rust implementation is preferred. Install to repo-local directory:

cargo install --path tools/demoswarm-runs-tools --root .demoswarm

The shim will automatically resolve in order:

.demoswarm/bin/demoswarm (repo-local install, preferred)
demoswarm on PATH (global install)
cargo run fallback (dev environments)
Python fallback (legacy)

runs-index

When & Why to Use This Skill

Use Cases