| name | zworkforce-zarvis-runtime-orchestration |
| description | Implement and review Z.A.R.V.I.S. runtime skills, agent manifests, scheduled/continuous execution, handoffs, capability policy, supervision, and trace-driven improvements using existing zWorkforce durable execution and approval boundaries. |
zWorkforce Z.A.R.V.I.S. runtime orchestration
Use this skill when changing runtime skill catalogs, agent definitions, orchestrator routing, scheduled or continuous agents, agent handoffs, capability policy, operator supervision, or trace-driven optimization.
Required reading
AGENTS.mdpackages/zarvis/AGENTS.mdROADMAPS.mdexec-planning-zarvis.mdpackages/zarvis/docs/architecture/openjarvis-upgrade-map.mdpackages/zarvis/docs/architecture/skills-agents.mdpackages/zarvis/docs/requirements/master-requirements.md- relevant
services/zarvis-* contracts/tests
- relevant existing agent files under
packages/zarvis/agents/
Core rule
Do not port a parallel OpenJarvis runtime into zWorkforce. Adapt useful registry, skill and agent-mode concepts to the existing zWorkforce task, scheduler, policy, approval, audit and tenant model.
Runtime skill rules
Every product/runtime skill requires:
- stable ID and semantic version;
- input/output schemas;
- declared capabilities and allowed tools;
- mutability classification;
- approval policy;
- bounded timeout/concurrency;
- retry and idempotency semantics;
- audit mapping;
- owner and rollback/version policy.
Discovery does not imply authorization. Invalid or duplicate manifests fail closed. Generated/trace-mined skills are review candidates and must not auto-enable in production.
Agent-mode rules
Supported modes:
on_demandscheduledcontinuous
Use the existing durable zWorkforce scheduler/event infrastructure for scheduled work. Do not introduce a second scheduler.
Continuous mode must be implemented as bounded, supervised work with:
- lease/heartbeat;
- stale-run detection;
- max concurrency;
- rate limits;
- backoff/failure budget;
- pause/resume/disable;
- version pinning and rollback;
- bounded memory/session growth.
A continuous agent never receives unrestricted mutation rights merely because it is long-lived.
Handoff rules
- Handoffs are structured/versioned.
- The receiving agent cannot expand capabilities, tool scope or mutation scope.
- Prefer existing specialists instead of duplicating agents.
- Voice routing should hand off to existing code, memory, architecture, review and operations specialists when appropriate.
- The handoff preserves request/session/tenant correlation and deadline/budget.
Approval and mutation
- A model prediction, user speech transcript, scheduled trigger or continuous-agent decision is not by itself mutation approval.
- Mutating work remains behind the existing approval/action gateway.
- External side effects remain at-least-once where the platform documents that boundary; tools must use idempotency/fencing where applicable.
- Never turn retries into duplicate external mutations.
Registry rules
When adding registry/discovery abstractions:
- typed/scope-specific registries;
- deterministic discovery;
- duplicate rejection;
- explicit health/capability metadata where applicable;
- no silent cloud/provider enablement;
- explicit pinned-provider failures should be visible rather than silently substituted when correctness depends on the pin.
Trace-driven improvement
Traces may suggest routing or skill improvements, but automation must not self-promote unreviewed behavior into production.
Required promotion sequence:
- collect redacted evidence;
- generate candidate change;
- test offline/replay;
- policy/security review;
- bounded canary/versioned rollout;
- compare outcome, latency, cost and failure metrics;
- promote or rollback explicitly.
Tests
Add success and denial/failure coverage for:
- manifest validation;
- duplicate/cyclic skill dependencies;
- unknown capabilities/tools;
- mutating skill with missing approval policy;
- tenant isolation;
- scheduled occurrence idempotency;
- continuous lease/heartbeat/stale detection;
- rate/concurrency limits;
- pause/resume/disable;
- agent handoff scope narrowing;
- retries/idempotency;
- trace redaction;
- version rollback.
Validation
python -m compileall -q zworkforce tests scripts
PYTHONPATH=. python -m unittest discover -s tests -v
pnpm --dir packages/zarvis install --frozen-lockfile
pnpm --dir packages/zarvis peers check
pnpm --dir packages/zarvis test
pnpm --dir packages/zarvis audit --audit-level high
Run PostgreSQL-specific tests against a real PostgreSQL service whenever durable schema/lease/scheduler behavior changes. GitHub Actions remains the release gate.
