lhumina_code/hero_skills
4
0
Fork 0
Code Issues 33 Pull requests Projects Releases 1 Packages 1 Wiki Activity Actions

Add scaffold / check / refactor context skills + refresh existing service skills #260

New issue
Closed
opened 2026-05-18 12:37:11 +00:00 by timur · 6 comments
timur commented 2026-05-18 12:37:11 +00:00
Owner
Copy link

Goal

Produce the AI context (markdown skills) that lets an agent reliably:

  1. Scaffold a brand-new Hero service from the template.
  2. Check an existing service for compliance with the canonical pattern.
  3. Refactor a legacy service to match the canonical pattern.

These are documentation skills (md + toml sidecar per the new skills structure), not CLI tools. The actual scaffold/check tooling lives in hero_rpc and lab.

New skills to add (under skills/hero/service/)

hero_service_scaffold.md

When + how an agent should create a new Hero service. Steps:

  1. Confirm name, domain, schema with the user.
  2. Run hero_rpc scaffold <name> --schema <path> (link the hero_rpc issue).
  3. Open the preserved trait stub and fill in business logic.
  4. Run cargo build to trigger codegen, then lab infocheck until clean.
  5. lab service <name> --start and verify smoke tests pass.
    Reference: hero_rpc's upgraded example/recipe_server as the canonical end-to-end demo.

hero_service_refactor.md

How to migrate a legacy service (e.g. hero_inspector, the older hero_proc patterns, hand-rolled _ui admins) to the canonical template:

  1. Run lab infocheck — collect findings.
  2. For each finding, apply the canonical fix (cross-link to hero_service_check_fix).
  3. Replace hand-rolled SDKs with the generated one.
  4. Replace hand-rolled admin templates with framework components (cross-link to hero_website_framework).
  5. Drop Makefile / scripts/*.sh / service_<name>.nu per ADR-0001.
  6. Verify with lab infocheck clean exit + lab service smoke tests.

hero_service_check.md (or extend existing hero_service_check_fix)

Decide whether to extend the existing skill or split out a leaner check-only skill that an agent can run as a fast audit (without the fix recipes). Cross-link as appropriate.

Updates to existing skills

  • hero_service.md, hero_service_check_fix.md, hero_service_toml_info.md: audit for stale references.
    • Do NOT invert Askama→Tera references. Ecosystem default is compile-time Askama; Tera is reserved for runtime-templated content. Existing Askama mentions in the skills are correct — verify they describe compile-time use, not a default-Tera fallback. The framework's current Tera usage is the exception, not the rule.
    • Any mention of hero_admin_lib → hero_website_lib (after the framework alias issue lands).
    • Any mention of HeroLifecycle / HeroRpcServer / HeroUiServer from hero_service (the hero_rpc crate) → align with whichever wins in the codegen-alignment issue (recommendation: drop in favour of herolib_core::base + lab).
    • Reference hero_compute and latest-pulled hero_proc as the reference services; remove hero_inspector as a reference (it's out of date).
  • Naming: confirm _admin / _server / _sdk / _web / _app table is current; remove any _ui references.

Format

Per Kristof's recent skill reorganization:

  • One .md per skill, one .toml sidecar.
  • No YAML front matter.
  • Skills can include other skills (use this to avoid duplicating the wiring contract — point the scaffold skill at hero_service_toml_info and herolib_base instead of repeating their content).

Acceptance

  • An agent with no prior context can read hero_service_scaffold.md and produce a working service end-to-end.
  • An agent given a legacy repo can read hero_service_refactor.md and produce a lab infocheck-clean repo.
  • No skill in skills/hero/service/ mentions hero_admin_lib or hero_inspector as a positive example. (Askama mentions are fine and expected — it's the ecosystem default; just verify they describe compile-time use.)

Related

  • hero_rpc #scaffold-full-service-repo (the tool the scaffold skill drives)
  • hero_rpc #upgrade-recipe-server (the canonical example skills reference)
  • hero_website_framework alias-drop issue (this skill updates the docs after that lands)
## Goal Produce the AI context (markdown skills) that lets an agent reliably: 1. **Scaffold** a brand-new Hero service from the template. 2. **Check** an existing service for compliance with the canonical pattern. 3. **Refactor** a legacy service to match the canonical pattern. These are documentation skills (md + toml sidecar per the new skills structure), not CLI tools. The actual scaffold/check tooling lives in `hero_rpc` and `lab`. ## New skills to add (under `skills/hero/service/`) ### `hero_service_scaffold.md` When + how an agent should create a new Hero service. Steps: 1. Confirm name, domain, schema with the user. 2. Run `hero_rpc scaffold <name> --schema <path>` (link the hero_rpc issue). 3. Open the preserved trait stub and fill in business logic. 4. Run `cargo build` to trigger codegen, then `lab infocheck` until clean. 5. `lab service <name> --start` and verify smoke tests pass. Reference: hero_rpc's upgraded `example/recipe_server` as the canonical end-to-end demo. ### `hero_service_refactor.md` How to migrate a legacy service (e.g. `hero_inspector`, the older `hero_proc` patterns, hand-rolled `_ui` admins) to the canonical template: 1. Run `lab infocheck` — collect findings. 2. For each finding, apply the canonical fix (cross-link to `hero_service_check_fix`). 3. Replace hand-rolled SDKs with the generated one. 4. Replace hand-rolled admin templates with framework components (cross-link to hero_website_framework). 5. Drop `Makefile` / `scripts/*.sh` / `service_<name>.nu` per ADR-0001. 6. Verify with `lab infocheck` clean exit + `lab service` smoke tests. ### `hero_service_check.md` (or extend existing `hero_service_check_fix`) Decide whether to extend the existing skill or split out a leaner check-only skill that an agent can run as a fast audit (without the fix recipes). Cross-link as appropriate. ## Updates to existing skills - **`hero_service.md`**, **`hero_service_check_fix.md`**, **`hero_service_toml_info.md`**: audit for stale references. - **Do NOT invert Askama→Tera references.** Ecosystem default is compile-time **Askama**; Tera is reserved for runtime-templated content. Existing Askama mentions in the skills are correct — verify they describe compile-time use, not a default-Tera fallback. The framework's current Tera usage is the exception, not the rule. - Any mention of `hero_admin_lib` → `hero_website_lib` (after the framework alias issue lands). - Any mention of `HeroLifecycle` / `HeroRpcServer` / `HeroUiServer` from `hero_service` (the hero_rpc crate) → align with whichever wins in the codegen-alignment issue (recommendation: drop in favour of `herolib_core::base` + `lab`). - Reference `hero_compute` and latest-pulled `hero_proc` as the reference services; remove `hero_inspector` as a reference (it's out of date). - **Naming**: confirm `_admin` / `_server` / `_sdk` / `_web` / `_app` table is current; remove any `_ui` references. ## Format Per Kristof's recent skill reorganization: - One `.md` per skill, one `.toml` sidecar. - No YAML front matter. - Skills can include other skills (use this to avoid duplicating the wiring contract — point the scaffold skill at `hero_service_toml_info` and `herolib_base` instead of repeating their content). ## Acceptance - An agent with no prior context can read `hero_service_scaffold.md` and produce a working service end-to-end. - An agent given a legacy repo can read `hero_service_refactor.md` and produce a `lab infocheck`-clean repo. - No skill in `skills/hero/service/` mentions `hero_admin_lib` or `hero_inspector` as a positive example. (Askama mentions are fine and expected — it's the ecosystem default; just verify they describe compile-time use.) ## Related - hero_rpc #scaffold-full-service-repo (the tool the scaffold skill drives) - hero_rpc #upgrade-recipe-server (the canonical example skills reference) - hero_website_framework alias-drop issue (this skill updates the docs after that lands)
timur commented 2026-05-18 14:41:22 +00:00
Author
Owner
Copy link

Parent / context tracker: hero_skills#262 — read it before starting work on this issue. Locked decisions, reference materials, and execution order live there. Iterate via comments here; consolidation passes on the body only after feedback settles.

Parent / context tracker: [hero_skills#262](https://forge.ourworld.tf/lhumina_code/hero_skills/issues/262) — read it before starting work on this issue. Locked decisions, reference materials, and execution order live there. Iterate via comments here; consolidation passes on the body only after feedback settles.
timur commented 2026-05-18 14:54:12 +00:00
Author
Owner
Copy link

State refresh

Pulled latest. Skills directory has been reorganized into skills/hero/{config,proc,service,ui,networkprotocol}/ subdirs. The three service skills relevant to this issue stay at skills/hero/service/ — files unchanged in path:

  • hero_service.md + .toml
  • hero_service_toml_info.md + .toml
  • hero_service_check_fix.md + .toml

Action items in this issue are still valid. New context:

  • New scaffold/check/refactor skills land alongside the existing three at skills/hero/service/.
  • Cleanup pass on existing skills can start now (tier-1 work per META).
  • New skills wait on hero_rpc#54 (scaffolder shape) + #55 (codegen alignment) so they document the actual tool surface.
## State refresh Pulled latest. Skills directory has been reorganized into `skills/hero/{config,proc,service,ui,networkprotocol}/` subdirs. The three service skills relevant to this issue stay at `skills/hero/service/` — files unchanged in path: - `hero_service.md` + `.toml` - `hero_service_toml_info.md` + `.toml` - `hero_service_check_fix.md` + `.toml` Action items in this issue are still valid. New context: - New scaffold/check/refactor skills land alongside the existing three at `skills/hero/service/`. - Cleanup pass on existing skills can start now (tier-1 work per META). - New skills wait on [hero_rpc#54](https://forge.ourworld.tf/lhumina_code/hero_rpc/issues/54) (scaffolder shape) + [#55](https://forge.ourworld.tf/lhumina_code/hero_rpc/issues/55) (codegen alignment) so they document the actual tool surface.
timur commented 2026-05-18 15:06:36 +00:00
Author
Owner
Copy link

Tier-1 cleanup pass — done

Audited the three existing service skills (hero_service.md, hero_service_toml_info.md, hero_service_check_fix.md) for stale references per the action list.

Findings

Stale ref Found? Action
hero_admin_lib no none (and per #262, the alias-drop premise was wrong anyway — the two framework crates stay separate)
hero_inspector (positive example) no none
HeroLifecycle / HeroRpcServer / HeroUiServer from old hero_service crate no none — skills already point at herolib_core::base + lab
Tera (as default) no none — only Askama appears, which is the locked default; added a clarifying note that it's compile-time
_ui naming references yes fixed (see below)
_client (old SDK name) not previously called out added to bad-suffix list

Edits in 2a05555

  • hero_service_toml_info.md — dropped the legacy ui.sock / *_ui.sock rows from the router-card table; added a one-line note that admin.sock is canonical and _ui is out.
  • hero_service_check_fix.md — naming table now includes _sdk (Rust SDK lib crate, required when a server exists) and _examples (optional); added an Askama-as-compile-time-default note pointing at hero_admin_lib (Askama) vs hero_website_lib (Tera); added _client to the "fix needed if" bad-suffix list and broadened the grep accordingly.
  • hero_service.md — no changes needed; already aligned (uses admin / web / cli / cmdline enum values, no _ui references).

Held back (tier 3 — waits on hero_rpc#54 + #55)

Per the May-18 state-refresh comment, the new scaffold / check / refactor skills wait on the scaffolder shape (hero_rpc#54) and codegen alignment (hero_rpc#55) so they describe the actual tool surface. Will pick those up once those land.

## Tier-1 cleanup pass — done Audited the three existing service skills (`hero_service.md`, `hero_service_toml_info.md`, `hero_service_check_fix.md`) for stale references per the action list. ### Findings | Stale ref | Found? | Action | |---|---|---| | `hero_admin_lib` | no | none (and per #262, the alias-drop premise was wrong anyway — the two framework crates stay separate) | | `hero_inspector` (positive example) | no | none | | `HeroLifecycle` / `HeroRpcServer` / `HeroUiServer` from old `hero_service` crate | no | none — skills already point at `herolib_core::base` + `lab` | | `Tera` (as default) | no | none — only `Askama` appears, which is the locked default; added a clarifying note that it's compile-time | | `_ui` naming references | yes | fixed (see below) | | `_client` (old SDK name) | not previously called out | added to bad-suffix list | ### Edits in `2a05555` - `hero_service_toml_info.md` — dropped the legacy `ui.sock` / `*_ui.sock` rows from the router-card table; added a one-line note that `admin.sock` is canonical and `_ui` is out. - `hero_service_check_fix.md` — naming table now includes `_sdk` (Rust SDK lib crate, required when a server exists) and `_examples` (optional); added an Askama-as-compile-time-default note pointing at `hero_admin_lib` (Askama) vs `hero_website_lib` (Tera); added `_client` to the "fix needed if" bad-suffix list and broadened the grep accordingly. - `hero_service.md` — no changes needed; already aligned (uses `admin` / `web` / `cli` / `cmdline` enum values, no `_ui` references). ### Held back (tier 3 — waits on hero_rpc#54 + #55) Per the May-18 state-refresh comment, the **new** scaffold / check / refactor skills wait on the scaffolder shape (hero_rpc#54) and codegen alignment (hero_rpc#55) so they describe the actual tool surface. Will pick those up once those land.
timur commented 2026-05-18 23:18:27 +00:00
Author
Owner
Copy link

Pushed tier-1 cleanup on branch development_timur (commit 2a05555).

Two files changed, +9 / -4. Tier-3 (new scaffold/refactor/check skills) stays parked here in #260 until hero_rpc#54 + #55 land — no follow-up issue needed since the remaining deliverables are already in this issue's body and the blockers are linked from the META (#262).

Pushed tier-1 cleanup on branch `development_timur` (commit `2a05555`). - Branch: https://forge.ourworld.tf/lhumina_code/hero_skills/src/branch/development_timur - Diff vs `development`: https://forge.ourworld.tf/lhumina_code/hero_skills/compare/development...development_timur Two files changed, +9 / -4. Tier-3 (new scaffold/refactor/check skills) stays parked here in #260 until hero_rpc#54 + #55 land — no follow-up issue needed since the remaining deliverables are already in this issue's body and the blockers are linked from the META (#262).
timur commented 2026-05-19 02:39:03 +00:00
Author
Owner
Copy link

Tier-3 — new scaffold / check / refactor skills landed

Pushed three new skills on development_timur (d97366a). Diff vs development: https://forge.ourworld.tf/lhumina_code/hero_skills/compare/development...development_timur

What's new under skills/hero/service/

File Purpose
hero_service_scaffold.md + .toml End-to-end flow for creating a new Hero service via the WorkspaceScaffolder (library API + hero_rpc_generator CLI). Documents the generated 5-crate layout, the known gaps the scaffolder doesn't yet emit (Makefile/buildenv.sh removal, _examples, PURPOSE.md, README.md, .forgejo/workflows/build-linux.yaml, hero_rpc2 trait SDK pending), and the post-scaffold validation loop.
hero_service_check.md + .toml Fast read-only audit — single command (lab infocheck); per-dimension spot-checks (naming, service.toml, base wiring, socket paths, lab-driven lifecycle, OpenRPC); live smoke-test recipe; finding-to-fix pointer table referencing hero_service_check_fix. Split from _check_fix per the issue body's "leaner check-only skill" option.
hero_service_refactor.md + .toml Migrating legacy services. Step-by-step plan (baseline → rename _ui/_client → fix service.toml → rewrite main.rs against herolib_core::base → swap admin to hero_admin_lib → stage SDK toward hero_rpc2 trait emitter → drop Makefile/scripts/.nu → regenerate PURPOSE.md/README.md → add _examples → add release CI). Drives the lab infocheck fix-loop.

Source-of-truth check

  • Pulled hero_rpc development and issue-55-codegen-alignment. §1–§6 of #55 are landed on the branch (from_service_toml, _admin via hero_admin_lib, §5 main.rs boilerplate, _admin/_sdk naming, per-binary service.toml, hero_lifecycle rename, hero_rpc2 vendor + context types + HTTP wiring + scaffolded trait/Python SDK emitters). Skills describe what the scaffolder produces today on that branch, with explicit "known gaps" pointers for the deltas #54 still tracks.
  • All cross-links are by skill name ([name](name)) — hero_service_toml_info, herolib_base, hero_sockets, hero_service_check_fix, forge-release-workflow, etc. — so agents follow the wiring rules from those skills without duplication.
  • hero_inspector is referenced only as a negative example ("do not model on this — out of date"), per the acceptance criteria. No mention of hero_admin_lib as something to drop (kept as the canonical admin foundation per parent META).
  • All three files follow the established hero/service/ format: pure markdown body + .toml sidecar (description, technology, links, tags, purposes), no YAML frontmatter.

Acceptance from the issue body

  • An agent with no prior context can read hero_service_scaffold.md and produce a working service end-to-end. (Inputs table → scaffold flow → known gaps to patch by hand → lab infocheck + lab service --install/--start validation → acceptance checklist.)
  • An agent given a legacy repo can read hero_service_refactor.md and produce a lab infocheck-clean repo. (Ten-step migration plan + explicit acceptance criteria + reference to hero_service_check_fix for per-finding recipes.)
  • No skill in skills/hero/service/ mentions hero_admin_lib or hero_inspector as a positive example. (hero_admin_lib appears only where the META locks it in as the admin foundation; hero_inspector appears only with "do NOT mimic.")

Closing this issue

All tier-3 deliverables in the issue body are landed. The downstream pieces flagged as "known gaps" in hero_service_scaffold.md (Makefile/buildenv.sh deletion in scaffolder, _examples crate emission, PURPOSE.md / README.md / .forgejo/workflows/build-linux.yaml generation, hero_rpc2 trait translator) stay with hero_rpc#54 + #55 §2 part 4 and don't belong here. Once both land, the "known gaps" section of hero_service_scaffold.md can shrink in a follow-up cleanup pass on this repo.

Marking this complete on my side — ready for review.

## Tier-3 — new scaffold / check / refactor skills landed Pushed three new skills on `development_timur` ([`d97366a`](https://forge.ourworld.tf/lhumina_code/hero_skills/commit/d97366a)). Diff vs `development`: https://forge.ourworld.tf/lhumina_code/hero_skills/compare/development...development_timur ### What's new under `skills/hero/service/` | File | Purpose | |---|---| | [`hero_service_scaffold.md`](https://forge.ourworld.tf/lhumina_code/hero_skills/src/branch/development_timur/skills/hero/service/hero_service_scaffold.md) + `.toml` | End-to-end flow for creating a new Hero service via the `WorkspaceScaffolder` (library API + `hero_rpc_generator` CLI). Documents the generated 5-crate layout, the known gaps the scaffolder doesn't yet emit (Makefile/buildenv.sh removal, `_examples`, `PURPOSE.md`, `README.md`, `.forgejo/workflows/build-linux.yaml`, hero_rpc2 trait SDK pending), and the post-scaffold validation loop. | | [`hero_service_check.md`](https://forge.ourworld.tf/lhumina_code/hero_skills/src/branch/development_timur/skills/hero/service/hero_service_check.md) + `.toml` | Fast read-only audit — single command (`lab infocheck`); per-dimension spot-checks (naming, `service.toml`, base wiring, socket paths, `lab`-driven lifecycle, OpenRPC); live smoke-test recipe; finding-to-fix pointer table referencing `hero_service_check_fix`. Split from `_check_fix` per the issue body's "leaner check-only skill" option. | | [`hero_service_refactor.md`](https://forge.ourworld.tf/lhumina_code/hero_skills/src/branch/development_timur/skills/hero/service/hero_service_refactor.md) + `.toml` | Migrating legacy services. Step-by-step plan (baseline → rename `_ui`/`_client` → fix `service.toml` → rewrite `main.rs` against `herolib_core::base` → swap admin to `hero_admin_lib` → stage SDK toward hero_rpc2 trait emitter → drop Makefile/scripts/`.nu` → regenerate `PURPOSE.md`/`README.md` → add `_examples` → add release CI). Drives the `lab infocheck` fix-loop. | ### Source-of-truth check - Pulled `hero_rpc` `development` and `issue-55-codegen-alignment`. §1–§6 of #55 are landed on the branch (`from_service_toml`, `_admin` via `hero_admin_lib`, §5 `main.rs` boilerplate, `_admin`/`_sdk` naming, per-binary `service.toml`, `hero_lifecycle` rename, hero_rpc2 vendor + context types + HTTP wiring + scaffolded trait/Python SDK emitters). Skills describe **what the scaffolder produces today** on that branch, with explicit "known gaps" pointers for the deltas #54 still tracks. - All cross-links are by skill name (`[name](name)`) — `hero_service_toml_info`, `herolib_base`, `hero_sockets`, `hero_service_check_fix`, `forge-release-workflow`, etc. — so agents follow the wiring rules from those skills without duplication. - `hero_inspector` is referenced only as a negative example ("do not model on this — out of date"), per the acceptance criteria. No mention of `hero_admin_lib` as something to drop (kept as the canonical admin foundation per parent META). - All three files follow the established `hero/service/` format: pure markdown body + `.toml` sidecar (description, technology, links, tags, purposes), no YAML frontmatter. ### Acceptance from the issue body - [x] An agent with no prior context can read `hero_service_scaffold.md` and produce a working service end-to-end. *(Inputs table → scaffold flow → known gaps to patch by hand → `lab infocheck` + `lab service --install/--start` validation → acceptance checklist.)* - [x] An agent given a legacy repo can read `hero_service_refactor.md` and produce a `lab infocheck`-clean repo. *(Ten-step migration plan + explicit acceptance criteria + reference to `hero_service_check_fix` for per-finding recipes.)* - [x] No skill in `skills/hero/service/` mentions `hero_admin_lib` or `hero_inspector` as a positive example. *(`hero_admin_lib` appears only where the META locks it in as the admin foundation; `hero_inspector` appears only with "do NOT mimic.")* ### Closing this issue All tier-3 deliverables in the issue body are landed. The downstream pieces flagged as "known gaps" in `hero_service_scaffold.md` (Makefile/buildenv.sh deletion in scaffolder, `_examples` crate emission, `PURPOSE.md` / `README.md` / `.forgejo/workflows/build-linux.yaml` generation, hero_rpc2 trait translator) stay with hero_rpc#54 + #55 §2 part 4 and don't belong here. Once both land, the "known gaps" section of `hero_service_scaffold.md` can shrink in a follow-up cleanup pass on this repo. Marking this complete on my side — ready for review.
timur commented 2026-05-19 13:40:27 +00:00
Author
Owner
Copy link

Closing — work landed. Both halves done: tier-1 cleanup pass in 0634d4d; new scaffold/check/refactor skills in PR #264 (merged 3b04435).

Closing — work landed. Both halves done: tier-1 cleanup pass in `0634d4d`; new scaffold/check/refactor skills in PR #264 (merged 3b04435).
timur closed this issue 2026-05-19 13:40:27 +00:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
development
pr-260-new-skills
development_timur
docs/setup-bootstrap-adr
main
lab-latest
latest
Labels
Clear labels   
prio_critical

   
prio_low

   
type_bug

   
type_contact

   
type_issue

   
type_lead

   
type_question

   
type_story

   
type_task
No labels
prio_critical
prio_low
type_bug
type_contact
type_issue
type_lead
type_question
type_story
type_task
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
lhumina_code/hero_skills#260
No description provided.