Runtime operator

Runtime Operator

Runtime Operator adds a real, project-local runtime layer under .agent/. It does not create unlimited autonomy, but it makes long-task operation resumable, inspectable, queue-driven, and ready for Codex automations or external sync.

Trigger Conditions

Use this skill when:

• The user asks to reduce gaps around automatic continuation, tool scheduling, external state sync, long-term memory retrieval, or task queues.
• A long-running project needs queue state, event logs, memory search, or resume prompts.
• $project-commander needs a harder runtime substrate than Markdown-only memory.
• Codex automations, GitHub/CI/task-board sync, or MCP integration must be prepared.

Do Not Trigger

Do not use this skill when:

• The task is a simple one-shot answer.
• The user forbids creating .agent/state/ or scripts.
• A project already mandates a different runtime/state system.

Runtime Files

Maintain:

• .agent/state/tasks.jsonl: durable local task queue.
• .agent/state/events.jsonl: append-only runtime event log.
• .agent/state/memory-index.json: searchable local memory index.
• .agent/state/sync-outbox.jsonl: external sync actions waiting for a target.
• .agent/state/sync-export.json: latest sync snapshot.
• .agent/state/sync-targets.json: sync target policy and requirements.
• .agent/state/automation-profile.json: automation readiness settings.
• .agent/resume-prompt.md: prompt for future Codex sessions or automations.
• .agent/automation-prompt.md: prompt body for a Codex heartbeat/cron automation.
• .agent/RUNTIME.md: human-readable runtime operating guide.
• .agent/GATES.md: required verification gates.

Script

Use:

py -3 .\.agents\skills\persistent-memory\scripts\shenhua_runtime.py <command>

Key commands:

• init: create runtime state files and prompts.
• task add <title>: add a task to the local queue.
• task list: show queue status.
• task update <id> --status done --note "..."
• event --type <type> --message "..."
• index: rebuild local memory index.
• search <query>: search indexed project memory.
• resume: regenerate .agent/resume-prompt.md.
• automation-prompt: regenerate .agent/automation-prompt.md.
• sync-export: export queue/events/handoff for external sync.
• gate: run runtime self-checks, skill validation, memory index, and resume generation.

Five Gap Minimization

1. Automatic persistent running:
   • Generate an automation prompt and runtime queue.
   • Use Codex heartbeat/cron automation only after a user chooses cadence.
2. Forced tool scheduling:
   • Encode gates in AGENTS.md, skills, and gate.
   • Use CI or external checks for hard enforcement when available.
3. External state sync:
   • Export a machine-readable outbox and sync snapshot.
   • Actual remote writes require the chosen target, credentials, and MCP/CLI availability.
4. Long-term memory retrieval:
   • Rebuild and query .agent/state/memory-index.json.
   • Upgrade to SQLite/vector/MCP memory only when project scale needs it.
5. Platform-level task queue:
   • Use .agent/state/tasks.jsonl as the local queue.
   • Mirror it to GitHub Issues/Projects, Linear, or other systems when configured.

Required .agent/ Updates

Always update:

• .agent/LOG.md
• .agent/TASKS.md
• .agent/HANDOFF.md

When runtime state changes, also update:

• .agent/state/events.jsonl
• .agent/state/tasks.jsonl when queue tasks change
• .agent/resume-prompt.md after major state changes

Other Skills

• Use $project-commander for choosing the next task.
• Use $persistent-memory for memory hygiene.
• Use $verification-loop after script or state changes.
• Use $self-reviewer and $handoff-writer before ending.

Subagents

Runtime Operator does not require subagents. Subagents can consume tasks from tasks.jsonl only when the current Codex runtime and user authorization permit delegation.

Verification

Run:

py -3 .\.agents\skills\persistent-memory\scripts\shenhua_runtime.py gate

The gate must pass before claiming the runtime layer is ready.

Output Format

RUNTIME STATUS
Queue:
Events:
Memory index:
Automation readiness:
External sync:
Gate result:
Remaining hard limits: