feat(skills): add hero_rust_repo_create — canonical Hero Rust workspace layout #144

Merged

mahmoud merged 2 commits from development_skill_hero_rust_repo_create into development

2026-04-27 18:14:24 +00:00

mahmoud commented

2026-04-27 17:59:07 +00:00

Owner

Summary

Adds hero_rust_repo_create — an umbrella skill that walks a coding agent through creating a new Hero Rust repository, or aligning an existing one, to the canonical workspace layout shared by hero_compute and hero_books.

Why

We just spent four PRs (hero_books #97, #109, #110, #111) bringing hero_books into line with hero_compute. The pattern that emerged is coherent enough to deserve its own skill — but no existing skill covers it end-to-end. hero_crates_best_practices_check covers the multi-crate architecture; repo_check covers build automation; hero_sockets / hero_proc_service_selfstart / naming_convention each cover one slice. Nothing tied them together with the layout layer (workspace.package, scripts triplet, docs flatness, README section order, Makefile target set).

Next time someone scaffolds a new Hero Rust service, this skill is the single entry point — and the focused skills remain the source of truth for their own subsystems.

What's in it

11-step procedure from empty directory to running service:
1. Workspace setup ([workspace] + [workspace.package] + resolver = "3")
2. Crate structure (<n> / <n>_lib / <n>_server / <n>_sdk + optional _ui / _admin / _examples / _lib_rhai)
3. Sockets and selfstart
4. Scripts (build_lib.sh, buildenv.sh, configure.sh, install.sh, uninstall.sh)
5. Documentation (flat docs/, semantic filenames)
6. README (canonical section order)
7. Makefile targets
8. CI workflows
9. Nushell service module
10. Optional admin UI bits, whitelists, auth, TUI
11. Verification (best-practices check + repo check + smoke build/run)
Each step references the existing focused skill — does not duplicate it.
Hard rules called out separately because they trip people up:
- No root src/; binaries live in their own crate
- Root Cargo.toml has no [package]; pure [workspace] + [workspace.package]
- buildenv.sh in scripts/, not at repo root
- docs/ is flat; no manual/ subdirectory
- Unix sockets only, per-service directory under $HERO_SOCKET_DIR
- Only the unsuffixed CLI does --start/--stop/--status
A "Quick checklist" at the bottom you can pin while running the skill.
Pointers to the four reference PRs in hero_books so anyone aligning an existing repo has worked examples to follow.

Test plan

Manual review of the SKILL.md.
Smoke-test by triggering it on a fresh empty directory; confirm an agent can produce a workspace that builds.
(Future) Use it for the next new Hero Rust service we create; treat any divergence as a bug in the skill.

🤖 Generated with Claude Code

## Summary Adds `hero_rust_repo_create` — an umbrella skill that walks a coding agent through creating a new Hero Rust repository, or aligning an existing one, to the canonical workspace layout shared by [`hero_compute`](https://forge.ourworld.tf/lhumina_code/hero_compute) and [`hero_books`](https://forge.ourworld.tf/lhumina_code/hero_books). ## Why We just spent four PRs (`hero_books` #97, #109, #110, #111) bringing `hero_books` into line with `hero_compute`. The pattern that emerged is coherent enough to deserve its own skill — but no existing skill covers it end-to-end. `hero_crates_best_practices_check` covers the multi-crate architecture; `repo_check` covers build automation; `hero_sockets` / `hero_proc_service_selfstart` / `naming_convention` each cover one slice. Nothing tied them together with the layout layer (workspace.package, scripts triplet, docs flatness, README section order, Makefile target set). Next time someone scaffolds a new Hero Rust service, this skill is the single entry point — and the focused skills remain the source of truth for their own subsystems. ## What's in it - 11-step procedure from empty directory to running service: 1. Workspace setup (`[workspace]` + `[workspace.package]` + `resolver = "3"`) 2. Crate structure (`<n>` / `<n>_lib` / `<n>_server` / `<n>_sdk` + optional `_ui` / `_admin` / `_examples` / `_lib_rhai`) 3. Sockets and selfstart 4. Scripts (`build_lib.sh`, `buildenv.sh`, `configure.sh`, `install.sh`, `uninstall.sh`) 5. Documentation (flat `docs/`, semantic filenames) 6. README (canonical section order) 7. Makefile targets 8. CI workflows 9. Nushell service module 10. Optional admin UI bits, whitelists, auth, TUI 11. Verification (best-practices check + repo check + smoke build/run) - Each step **references** the existing focused skill — does not duplicate it. - Hard rules called out separately because they trip people up: - No root `src/`; binaries live in their own crate - Root `Cargo.toml` has no `[package]`; pure `[workspace]` + `[workspace.package]` - `buildenv.sh` in `scripts/`, not at repo root - `docs/` is flat; no `manual/` subdirectory - Unix sockets only, per-service directory under `$HERO_SOCKET_DIR` - Only the unsuffixed CLI does `--start`/`--stop`/`--status` - A "Quick checklist" at the bottom you can pin while running the skill. - Pointers to the four reference PRs in `hero_books` so anyone aligning an existing repo has worked examples to follow. ## Test plan - [ ] Manual review of the SKILL.md. - [ ] Smoke-test by triggering it on a fresh empty directory; confirm an agent can produce a workspace that builds. - [ ] (Future) Use it for the next new Hero Rust service we create; treat any divergence as a bug in the skill. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

mahmoud added 1 commit

2026-04-27 17:59:07 +00:00

feat(skills): add hero_rust_repo_create — canonical Hero Rust workspace layout

Build and Publish Skills / build-and-publish (pull_request) Failing after 0s

Details

6d9e6d6ef1

Umbrella skill for creating a new Hero Rust repository (or aligning an
existing one) to the canonical layout shared by hero_compute and
hero_books. Captures the pattern that emerged from aligning hero_books
in hero_books PRs #97/#109/#110/#111.

Walks an agent through 11 steps from empty directory to running service:
workspace shape, crate split, sockets + selfstart, scripts triplet,
docs/ layout, README section order, Makefile targets, CI workflows,
nu_service module, optional admin UI bits, verification.

Each step references the existing focused skill that owns the details
(hero_sockets, hero_proc_service_selfstart, build_lib, makefile_helper,
forge-release-workflow, nu_service, testing_suite, hero_crates_best_
practices_check, etc.) instead of duplicating them. The skill is the
orchestrator; the focused skills remain the source of truth for their
own subsystems.

Hard rules called out explicitly because they trip people up:
- No root src/; binaries live in their own crate.
- Root Cargo.toml has no [package]; pure [workspace] + [workspace.package].
- buildenv.sh in scripts/, not at repo root.
- docs/ is flat; no manual/ subdirectory.
- Unix sockets only; per-service directory under $HERO_SOCKET_DIR.
- Only the unsuffixed CLI does --start/--stop/--status (selfstart).

Reference repos (both at version 0.1.5+ with the canonical layout fully
applied as of 2026-04): hero_compute, hero_books.

mahmoud added 1 commit

2026-04-27 18:13:26 +00:00

fix(hero_rust_repo_create): mark configure/install/uninstall as optional

Build and Publish Skills / build-and-publish (pull_request) Successful in 3s

Details

862eaa78a6

These three scripts are only needed when a project ships a standalone
end-user install path outside the Hero ecosystem (e.g. hero_compute's
public curl-able installer). For internal Hero services that users
always install via service_<n> install from hero_skills, the nu module
is the canonical install path and the three scripts are unnecessary.

Updates:
- Output diagram: mark configure.sh / install.sh / uninstall.sh as
  optional, and call out that build_lib.sh, buildenv.sh, nu_service.nu
  are the required ones.
- Step 4 (Scripts): split the table into required vs optional; add a
  "When to add the optional three" decision rule with the question
  "Does this project have an audience that installs it without
  hero_skills?".
- Step 7 (Makefile): note that the configure / uninstall make targets
  are conditional on the optional scripts being present.
- Step 6 (README): make the Quick Start guidance conditional —
  Hero-native is always there; the curl one-liner only appears if the
  project has install.sh.
- Quick checklist: stop demanding the three optional scripts; gate them
  on whether the project ships a public installer.