Runs Derive

Runs Derive Skill

Read-only, deterministic helpers for .runs/ derivation. Use when cleanup agents need mechanical counts/extraction without interpretation.

Invocation

Always invoke via the shim:

bash .claude/scripts/demoswarm.sh <command> [options]

The shim resolves implementation in order:

1. .demoswarm/bin/demoswarm (Rust binary, preferred)
2. demoswarm on PATH (global install)
3. cargo run fallback (dev environments)
4. Python fallback (legacy)

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.

Null over guess (counts)

• File/dir missing → null (NOT 0)
• Present but no matches → 0
• Present but unparseable / tool error → null

No writes

This skill only reads. Index updates use runs-index. Secrets use secrets-tools.

Command Reference

Quick Examples

Counting patterns (stable markers)

# Count functional requirements
bash .claude/scripts/demoswarm.sh count pattern \
  --file ".runs/feat-auth/signal/requirements.md" \
  --regex '^### REQ-' \
  --null-if-missing
# stdout: 5 (or null if missing)

# Count NFRs
bash .claude/scripts/demoswarm.sh count pattern \
  --file ".runs/feat-auth/signal/requirements.md" \
  --regex '^### NFR-' \
  --null-if-missing

# Count BDD scenarios
bash .claude/scripts/demoswarm.sh count bdd \
  --dir ".runs/feat-auth/signal/features" \
  --null-if-missing

# Count open questions (QID marker)
bash .claude/scripts/demoswarm.sh count pattern \
  --file ".runs/feat-auth/signal/open_questions.md" \
  --regex '^- QID: OQ-SIG-[0-9]{3}' \
  --null-if-missing

# Count risks by severity
bash .claude/scripts/demoswarm.sh count pattern \
  --file ".runs/feat-auth/signal/early_risks.md" \
  --regex '^- RSK-[0-9]+ \[CRITICAL\]' \
  --null-if-missing

Extracting Machine Summary fields

# Get status from critic
bash .claude/scripts/demoswarm.sh ms get \
  --file ".runs/feat-auth/signal/requirements_critique.md" \
  --section "## Machine Summary" \
  --key "status" \
  --null-if-missing
# stdout: VERIFIED (or null)

# Get recommended_action
bash .claude/scripts/demoswarm.sh ms get \
  --file ".runs/feat-auth/build/code_critique.md" \
  --section "## Machine Summary" \
  --key "recommended_action" \
  --null-if-missing

Reading receipt fields

# Read merge verdict from gate receipt
bash .claude/scripts/demoswarm.sh receipt get \
  --file ".runs/feat-auth/gate/gate_receipt.json" \
  --key "merge_verdict" \
  --null-if-missing
# stdout: MERGE (or null)

# Read prior flow status
bash .claude/scripts/demoswarm.sh receipt get \
  --file ".runs/feat-auth/plan/plan_receipt.json" \
  --key "status" \
  --null-if-missing

Extracting YAML block fields

# Get deployment verdict
bash .claude/scripts/demoswarm.sh yaml get \
  --file ".runs/feat-auth/deploy/deployment_decision.md" \
  --key "deployment_verdict" \
  --null-if-missing
# stdout: STABLE (or null)

# Get Gate Result status from merge decision
bash .claude/scripts/demoswarm.sh yaml get \
  --file ".runs/feat-auth/gate/merge_decision.md" \
  --key "status" \
  --null-if-missing

Counting items in YAML blocks

# Count blockers array length
bash .claude/scripts/demoswarm.sh yaml count-items \
  --file ".runs/feat-auth/gate/merge_decision.md" \
  --item-regex '^[[:space:]]*- check:' \
  --null-if-missing

Timestamp generation

bash .claude/scripts/demoswarm.sh time now
# stdout: 2025-12-12T10:30:00Z

Contract Rules

1. stdout: Always a single scalar (null, integer, or string)
2. exit code: Always 0 (errors expressed via null stdout)
3. stderr: Optional diagnostics (never required for parsing)
4. null semantics: Missing file → null, no matches → 0
5. template leak guard: Values containing | or < → null

For Agent Authors

When writing cleanup agents:

1. Use runs-derive — bash .claude/scripts/demoswarm.sh ...
2. Do not embed grep|sed|awk|jq pipelines — use shim commands
3. Trust the contract — helpers handle edge cases consistently
4. Add blockers for nulls — when a count is null, explain why

Example pattern:

REQ_COUNT=$(bash .claude/scripts/demoswarm.sh count pattern \
  --file ".runs/${RUN_ID}/signal/requirements.md" \
  --regex '^### REQ-' \
  --null-if-missing)

if [[ "$REQ_COUNT" == "null" ]]; then
  BLOCKERS+=("requirements.md missing or unparseable")
fi

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:

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