Create skill for hero_rpc server lifecycle with zinit (OServer::run_cli pattern)

timur commented

2026-03-09 13:04:50 +00:00

Owner

Context

hero_rpc#7 added zinit lifecycle management to hero_rpc_server. Generated servers now use OServer::run_cli() which provides unified CLI subcommands: start, stop, run, status, logs, ui, zinit.

This is a new standard pattern that all hero services should follow. We need a skill that teaches AI how to use it.

What's needed

1. New skill: `hero_rpc_server_lifecycle`

Should document:

OServer::run_cli() pattern — the entry point for all generated servers

OServer::run_cli("service_name", "description", |server, contexts, seed_dir, seed_domains| async move {
    for ctx in &contexts {
        server.register::<OsisDomain>(ctx, "domain").await?;
    }
    server.run().await
}).await?;

CLI subcommands — start (zinit), stop, run (dev), status, logs, ui, zinit
ZinitLifecycle struct — Pattern B (ZinitRPCAPIClient), how it registers ActionSpec + ServiceConfig
Socket conventions — ~/hero/var/sockets/hero_db_{context}_{domain}.sock
Scaffold generator — how hero_rpc_generator creates the 5-crate workspace with this pattern baked in
When to use what: start for production (zinit-managed), run for development (direct)

2. Update existing skills

The following skills reference the OLD server patterns and need updating:

hero_service — references manual zinit add/zinit start in Makefile; should mention that hero_rpc-generated servers have this built into the binary via OServer::run_cli()
hero_openrpc_server_admin_template — documents manual server setup with UnixRpcServer::new(); needs section on the generated OServer pattern
zinit_sdk — documents ZinitHandle (blocking) and AsyncZinitClient; should also reference ZinitRPCAPIClient (Pattern B, OpenRPC client) used by ZinitLifecycle
hero_ecosystem — may need updates to reference the new lifecycle pattern

3. Reference implementation

hero_rpc crates/server/src/server/cli.rs — ServerCli + ServerCommand
hero_rpc crates/server/src/server/lifecycle.rs — ZinitLifecycle
hero_rpc crates/server/src/server/server.rs — OServer::run_cli()
hero_rpc crates/generator/src/build/scaffold.rs — code generation template

See: lhumina_code/hero_rpc#7

## Context hero_rpc#7 added zinit lifecycle management to `hero_rpc_server`. Generated servers now use `OServer::run_cli()` which provides unified CLI subcommands: `start`, `stop`, `run`, `status`, `logs`, `ui`, `zinit`. This is a new standard pattern that all hero services should follow. We need a skill that teaches AI how to use it. ## What's needed ### 1. New skill: `hero_rpc_server_lifecycle` Should document: - **`OServer::run_cli()` pattern** — the entry point for all generated servers ```rust OServer::run_cli("service_name", "description", |server, contexts, seed_dir, seed_domains| async move { for ctx in &contexts { server.register::<OsisDomain>(ctx, "domain").await?; } server.run().await }).await?; ``` - **CLI subcommands** — start (zinit), stop, run (dev), status, logs, ui, zinit - **ZinitLifecycle struct** — Pattern B (ZinitRPCAPIClient), how it registers ActionSpec + ServiceConfig - **Socket conventions** — `~/hero/var/sockets/hero_db_{context}_{domain}.sock` - **Scaffold generator** — how `hero_rpc_generator` creates the 5-crate workspace with this pattern baked in - **When to use what**: `start` for production (zinit-managed), `run` for development (direct) ### 2. Update existing skills The following skills reference the OLD server patterns and need updating: - **`hero_service`** — references manual `zinit add`/`zinit start` in Makefile; should mention that hero_rpc-generated servers have this built into the binary via `OServer::run_cli()` - **`hero_openrpc_server_admin_template`** — documents manual server setup with `UnixRpcServer::new()`; needs section on the generated OServer pattern - **`zinit_sdk`** — documents `ZinitHandle` (blocking) and `AsyncZinitClient`; should also reference `ZinitRPCAPIClient` (Pattern B, OpenRPC client) used by `ZinitLifecycle` - **`hero_ecosystem`** — may need updates to reference the new lifecycle pattern ### 3. Reference implementation - hero_rpc `crates/server/src/server/cli.rs` — ServerCli + ServerCommand - hero_rpc `crates/server/src/server/lifecycle.rs` — ZinitLifecycle - hero_rpc `crates/server/src/server/server.rs` — OServer::run_cli() - hero_rpc `crates/generator/src/build/scaffold.rs` — code generation template See: https://forge.ourworld.tf/lhumina_code/hero_rpc/issues/7

timur commented

2026-03-09 13:13:00 +00:00

Author

Owner

Additional note: as part of hero_os#12, "contexts" are being renamed to "spaces" for end-user friendliness. The new skill should document both the internal concept (OSIS contexts) and the user-facing terminology (spaces). The OServer::run_cli() run subcommand uses --contexts but downstream services like hero_os may alias this to --spaces.

Additional note: as part of hero_os#12, "contexts" are being renamed to "spaces" for end-user friendliness. The new skill should document both the internal concept (OSIS contexts) and the user-facing terminology (spaces). The `OServer::run_cli()` run subcommand uses `--contexts` but downstream services like hero_os may alias this to `--spaces`.

timur commented

2026-03-10 07:41:59 +00:00

Author

Owner

Additional best practices to include in the skill, based on hero_os implementation:

zinit-only execution — there is no standalone/direct mode. The run subcommand is internal (what zinit invokes). Developers use start/stop/status/logs.
cargo update in make start — always run cargo update before building to pick up latest git dependency changes. Prevents stale hero_rpc bugs.
make run = start + stream logs + stop on Ctrl-C — for DX, make run starts via zinit, streams logs in foreground, and stops services on interrupt.
HTTP/UI crates also use ZinitLifecycle — not just OpenRPC servers. Any binary that should be supervised (e.g. hero_os_ui, static file servers) imports ZinitLifecycle from hero_rpc_server and gets the same start/stop/status/logs subcommands.
Fixed zinit socket path — ZinitLifecycle default was wrong (~/hero/var/zinit/zinit.sock), now corrected to ~/hero/var/sockets/zinit_server.sock matching zinit_server bind path.

Additional best practices to include in the skill, based on hero_os implementation: 1. **zinit-only execution** — there is no standalone/direct mode. The `run` subcommand is internal (what zinit invokes). Developers use `start/stop/status/logs`. 2. **`cargo update` in `make start`** — always run `cargo update` before building to pick up latest git dependency changes. Prevents stale `hero_rpc` bugs. 3. **`make run` = start + stream logs + stop on Ctrl-C** — for DX, `make run` starts via zinit, streams logs in foreground, and stops services on interrupt. 4. **HTTP/UI crates also use ZinitLifecycle** — not just OpenRPC servers. Any binary that should be supervised (e.g. `hero_os_ui`, static file servers) imports `ZinitLifecycle` from `hero_rpc_server` and gets the same `start/stop/status/logs` subcommands. 5. **Fixed zinit socket path** — `ZinitLifecycle` default was wrong (`~/hero/var/zinit/zinit.sock`), now corrected to `~/hero/var/sockets/zinit_server.sock` matching `zinit_server` bind path.

timur commented

2026-03-10 08:25:57 +00:00

Author

Owner

Skill Updated for Serve Rename

The hero_rpc_server_lifecycle skill has been updated (66a9897) to reflect the finalized naming convention:

run = developer command (start + stream logs + stop on Ctrl-C)
start = background start via zinit
serve = internal entry point (zinit calls this, never call manually)

Updates include:

CLI subcommand table and comparison matrix (run vs start vs serve)
ZinitLifecycle::run() method documented
Non-OpenRPC binary example updated with Serve pattern
Makefile best practices: make run delegates to cargo run -- run (no Makefile log polling)
Generated main.rs template updated

This skill should be considered complete for the current scope.

## Skill Updated for Serve Rename The `hero_rpc_server_lifecycle` skill has been updated (66a9897) to reflect the finalized naming convention: - `run` = developer command (start + stream logs + stop on Ctrl-C) - `start` = background start via zinit - `serve` = internal entry point (zinit calls this, never call manually) Updates include: - CLI subcommand table and comparison matrix (`run` vs `start` vs `serve`) - `ZinitLifecycle::run()` method documented - Non-OpenRPC binary example updated with `Serve` pattern - Makefile best practices: `make run` delegates to `cargo run -- run` (no Makefile log polling) - Generated `main.rs` template updated This skill should be considered complete for the current scope.

timur commented

2026-03-10 08:47:36 +00:00

Author

Owner

Serve Rename Convention Applied

The zinit lifecycle serve rename convention has been applied to all 4 target repos (hero_aibroker, hero_embedder, hero_index_server, hero_redis).

Changes follow the pattern documented in this issue:

run = developer command (start + stream logs + Ctrl-C stop)
serve = internal (what zinit invokes)
start/stop/status/logs = zinit management

All repos compile clean. Makefiles updated to use new subcommands.

Full details: lhumina_code/home#6

## Serve Rename Convention Applied The zinit lifecycle serve rename convention has been applied to all 4 target repos (hero_aibroker, hero_embedder, hero_index_server, hero_redis). Changes follow the pattern documented in this issue: - `run` = developer command (start + stream logs + Ctrl-C stop) - `serve` = internal (what zinit invokes) - `start/stop/status/logs` = zinit management All repos compile clean. Makefiles updated to use new subcommands. Full details: https://forge.ourworld.tf/lhumina_code/home/issues/6