pi-config/extensions/pi-crew/skills/runtime-state-reader/SKILL.md

name, description

name	description
runtime-state-reader	Safe read-only navigation of pi-crew run state. Use for inspecting manifests, tasks, events, agents, artifacts, health, and diagnostics without modifying state.

runtime-state-reader

Use this skill when debugging or auditing a pi-crew run.

Source patterns distilled

• src/state/types.ts, src/state/contracts.ts, src/state/state-store.ts
• src/state/event-log.ts, src/state/artifact-store.ts, src/runtime/crew-agent-records.ts
• src/extension/run-index.ts, src/extension/team-tool/status.ts, src/extension/team-tool/inspect.ts

Rules

• Prefer exported state APIs over direct file parsing: loadRunManifestById(cwd, runId), run index/list helpers, event readers, and agent readers.
• Treat state as append-mostly/durable. For review and debugging, do not mutate manifests/tasks/events.
• Validate run IDs and path-derived IDs; never concatenate untrusted path segments outside state helpers.
• Read events as JSONL; expect partial/corrupt trailing lines in crash scenarios and handle gracefully.
• Check status contracts before inferring behavior: terminal vs active run/task statuses matter.
• Agent aggregate records (agents.json) and per-agent status files can disagree briefly; prefer the latest loaded run state plus event log for final conclusions.
• Include exact paths inspected and distinguish direct evidence from inference.

Common inspection order

1. Load manifest/tasks.
2. Check run/task statuses and timestamps.
3. Read recent events.
4. Read agent records and per-agent output/status if needed.
5. Inspect artifacts/diagnostics only through contained paths.
6. Report root cause and smallest safe remediation.

Verification

For code changes to state readers:

cd pi-crew
npx tsc --noEmit
node --experimental-strip-types --test test/unit/run-index.test.ts test/unit/crew-contracts.test.ts test/unit/atomic-write.test.ts
npm test