houmao-touring

name	houmao-touring
description	Use Houmao's manual guided touring skill for users not yet familiar with Houmao.
license	MIT

Houmao Touring

houmao-touring is the Houmao-owned guide for users who are not yet familiar with Houmao. That includes first-run users, re-orienting operators, and developers inspecting system logic.

Use this skill only when the user explicitly asks for:

Trigger	Meaning
$houmao-touring	No-prompt orientation entrypoint.
A Houmao guided tour	Start the guided tour.
Houmao subsystem/component exploration	Explain Houmao by component area.

A bare invocation such as $houmao-touring means "start orientation now".

No-prompt behavior:

Do	Do Not
scan for existing Houmao project state.	Say only "the skill is now active."
infer the user's likely starting intent from that state.	Ask "how can I help?"
introduce Houmao in context.	Use any other empty open-ended greeting.
provide next-step instructions.	Wait for the user to know Houmao vocabulary.

Never answer a bare invocation with only a generic activation acknowledgement.

This skill teaches and routes. It does not own direct-operation command behavior.

Workflow

Start here for every invocation. Use the first matching row before loading any branch file.

Before workflow, answer explicit skill-help intent from ## Help and stop.

Step	First Look	Use It To
1	## Help	Answer explicit skill-help intent and stop.
2	## Entry Contract	Classify every non-help request before command execution.
3	## No-Prompt Entrypoint	Handle bare $houmao-touring and orientation requests with state inspection first.
4	### No-Prompt Choice Menu	Choose blank-workspace or project-ready choices from inspected state.
5	## Coverage Model	Map project-ready outcome requests to fast paths and check their project-overlay precondition.
6	## Branches	Load exactly one named branch after the user selects a path.
7	## Routing Guidance	Route concrete setup, runtime, mail, memory, loop, and lifecycle work to owning skills.
8	## Presentation Rules	Report compactly as result, status, next choices, and required input.

Launcher order:

Order	Launcher
1	houmao-mgr on PATH
2	uv tool run --from houmao houmao-mgr
3	Development launcher only if the first two do not satisfy the turn
User override	Follow an explicitly requested launcher

Help

When the user asks $houmao-touring help, help for houmao-touring, usage for houmao-touring, available functionality for houmao-touring, or what this skill can do, answer from this section and stop.

This is read-only help: do not run commands, mutate files, send mail, change gateway state, or alter managed-agent lifecycle state.

Available functionality:

Lane	Best For	What It Covers
Fast path use cases	Outcome-focused users	Learn Houmao by doing one useful end-to-end use case.
Subsystem exploration	Developer-minded users	Inspect Houmao by component area and owning route.

Fast path use cases:

Use Case	Intent	Main Route
Single Agent Full Run	Create and operate one fully functional managed agent.	Setup, definition, launch, gateway, mailbox, memory, inspection, and lifecycle work route to owning skills.
Operator-Controlled Agent Team	Create multiple fully functional agents and control them manually.	Multi-agent setup and live operations route to owning skills.
Pro Agent Loop	Define and construct a generated loop.	Generated loop construction routes through houmao-agent-loop-pro.

Common starting prompts:

Prompt	Intent
$houmao-touring help	Read-only help.
$houmao-touring	Orientation request.
$houmao-touring start a guided tour	Orientation request.
$houmao-touring orient me in this project	Orientation request.
$houmao-touring help me find the right starting path	Orientation request.
$houmao-touring create and operate one complete agent	Single Agent Full Run.
$houmao-touring create a manually controlled agent team	Operator-Controlled Agent Team.
$houmao-touring define a pro agent loop	Pro Agent Loop.
$houmao-touring explore Houmao by subsystem	Subsystem exploration.

Related skills and boundaries:

Boundary	Rule
Tour scope	Orient, teach nearby concepts, infer likely next path, and route.
Direct work	Route project, credential, definition, runtime, gateway, mailbox, memory, inspection, lifecycle, workspace, and loop work to owning skills.
Non-goal	Do not use touring as a broad skill catalog or default router for ordinary narrow requests.

Entry Contract

Classify the request before command execution.

Intent	Trigger Shape	First Action
Help intent	User asks for help, usage, or available functionality.	Answer ## Help and stop.
Orientation request	User invokes $houmao-touring or asks to start/orient.	Inspect current state, infer likely intent, offer best path plus alternatives.
Outcome request	User asks for one complete agent, a manual agent team, or a generated loop.	Inspect only safety-relevant state, then load branches/fast-paths.md.
Subsystem-exploration request	User asks for subsystem, component, internal, or working-logic exploration.	Load branches/subsystem-exploration.md.
Ordinary direct-operation request	User asks to create, launch, prompt, mail, inspect, stop, or clean up without asking for touring.	Do not activate touring; route to the owning skill.

For orientation and outcome requests, inspect current state before choosing a welcome shape or branch. For subsystem exploration, do not start the first-agent setup path by default.

No-Prompt Entrypoint

Bare $houmao-touring is the system entrypoint for a user who may know nothing about Houmao.

Required sequence:

Step	Action
1	Scan for existing Houmao project state.
2	Infer likely user intent from inspected state.
3	Introduce Houmao in the context of that state.
4	Present current posture, likely intent, next choices, and required input.
5	Wait for the user to confirm a path.

Scan:

Area	Inspection
Project	houmao-mgr project status
Definitions	houmao-mgr project specialist list; houmao-mgr project profile list when project state exists
Runtime	houmao-mgr agents global list
Live control	gateway, mailbox, and memory posture only when the selected next path needs them

Intent Guess Matrix

Inspected State	Likely Intent	First Choice
No project overlay	The user needs project foundation before agent workflows.	Create Houmao Project.
Project overlay exists, no specialists	The user is ready to define a launchable agent.	Single Agent Full Run, starting at agent definition.
Specialists or profiles exist, no running agents	The user is likely ready to launch and operate.	Single Agent Full Run, starting at launch readiness.
One running agent	The user likely wants to operate or inspect it.	Live operation choices inside Single Agent Full Run.
Multiple running agents	The user may want manual coordination.	Operator-Controlled Agent Team.
Existing loop artifacts or topology hints	The user may want generated orchestration.	Pro Agent Loop.
Component/internal/working-logic wording	The user wants component understanding.	Subsystem Exploration.

The guess orders choices. It must not execute concrete setup, launch, prompt, mail, gateway, memory, lifecycle, workspace, or loop work without user confirmation.

Fast paths are project-ready choices. If no Houmao project overlay exists, do not present Single Agent Full Run, Operator-Controlled Agent Team, or Pro Agent Loop as selectable no-prompt choices. Say those choices become available after project creation.

No-Prompt Response Shape

Use a compact response with these parts:

Part	Content
Intro	One sentence: Houmao creates, runs, inspects, and coordinates CLI-based AI agents with managed runtime, gateway, mailbox, memory, and loop support.
Current Posture	Compact project/definition/runtime/live-control status.
Likely Intent	The inferred path and why it fits.
Next Choices	Use the state-specific menu below. Without a project overlay, show exactly the three blank-workspace choices. With a project overlay, include the guessed path and Subsystem Exploration by name.
Required Input	Ask the user to pick a path, say inspect first, or say more detail.

If inspection cannot run, report current posture as unknown and offer inspect first as the first choice.

No-Prompt Choice Menu

For bare $houmao-touring, choose the menu from project posture. Adapt wording to the inspected state, but do not hide or rename Subsystem Exploration.

Blank workspace, no Houmao project overlay:

Choice	Intent	User Can Say	Route
Create Houmao Project	Initialize the foundation required by agent workflows.	create project	houmao-project-mgr
Subsystem Exploration	Understand Houmao by component area before creating state.	subsystems or a subsystem name	branches/subsystem-exploration.md
Inspect	Show current directory, project, and runtime evidence without mutation.	inspect	Read-only inspection

In this state, show only these three choices. Do not show Fast Path Use Cases, Single Agent Full Run, Operator-Controlled Agent Team, or Pro Agent Loop until a Houmao project overlay exists.

Project-ready workspace, Houmao project overlay exists:

Choice	Best For	User Can Say
Continue Likely Path	Follow the state-based guess.	continue
Fast Path Use Cases	Build useful Houmao workflows quickly.	single agent, team, or pro loop
Subsystem Exploration	Understand Houmao by component area.	subsystems or a subsystem name
Inspect First	See evidence before choosing.	inspect first

Do not collapse the project-ready menu into only fast path choices. If space is tight, keep the guessed path, Subsystem Exploration, and inspect first.

Subsystem Exploration Choices

When the no-prompt entrypoint offers Subsystem Exploration, include a compact preview of component choices. Load branches/subsystem-exploration.md only after the user selects this path or names one subsystem.

Choice	Subsystems	Best For
Project State	Project overlay, Agent definition	Where Houmao state lives and how agents become launchable.
Runtime Control	Managed runtime, Gateway	How agents run, expose live control, and report lifecycle.
Communication	Messaging, Mailbox	How prompts, operator mail, inter-agent mail, and notifier work connect.
Context and Evidence	Memory, Inspection	How durable context and read-only evidence guide decisions.
Multi-Agent Structure	Workspace, Loop orchestration	How isolated work areas and generated loops organize teams.

Keep this preview short. Use more detail or the branch page before expanding any subsystem.

Coverage Model

Lane	Purpose	Branch
Fast path use cases	Outcome-driven routes for useful end-to-end work.	branches/fast-paths.md
Subsystem exploration	Component-oriented explanation for system understanding.	branches/subsystem-exploration.md

Fast paths:

Precondition: a Houmao project overlay must exist. If missing, route Create Houmao Project through houmao-project-mgr, then return to fast-path selection after project setup.

Use Case	Coverage
Single Agent Full Run	Project overlay, tool/credential readiness, specialist/profile setup, foreground-first launch, gateway, mailbox, notification, prompt, inspection, memory, reminders, lifecycle follow-up.
Operator-Controlled Agent Team	Multiple agents, per-agent gateway/mailbox, prompts, mail, notifier, inspection, memory, reminders, lifecycle.
Pro Agent Loop	houmao-agent-loop-pro, loop intent, roles, tree-loop/generic-loop, mailbox/runtime contracts, workspace preparation when needed, validation, launch, operation.

Stages are posture labels, not a fixed route:

Stage	Typical Nearby Work
Beginner	Project overlay, mailbox basics, tool/credential readiness, specialist/profile setup, launch, first prompt.
Intermediate	Prompt, inspect, memo/pages, mailbox, gateway mail-notifier, reminders, manual coordination, lifecycle.
Advanced	Pro loop, lite loop, topology choice, isolated workspace, generated loop operation.

Presentation Rules

Rule	Instruction
Compact by default	Report only result, critical status, next choices, and required input.
Tables	Prefer small Markdown tables for status and choices. Keep tables at four columns or fewer.
Language	Use concise language. Focus on intent and current posture.
Detail	Use more detail for command examples, raw evidence, passive server context, deeper TUI tracking behavior, or architecture detail.
Ownership	Route by user intent. Do not duplicate detailed behavior, command syntax, options, or validation rules owned by other Houmao skills.

Presentation Examples

Operation result:

Area	Example Content
Result	What changed or what was learned.
Status	The one or two state facts that matter now.
Next	Nearby choices, routed by intent.
Need	Input needed to continue, if any.

Blank-workspace branch choices:

Choice	Intent	Route
Create Houmao Project	Create the project foundation needed by later agent workflows.	houmao-project-mgr
Subsystem Exploration	Inspect Houmao by component area.	Load branches/subsystem-exploration.md.
Inspect	Show current evidence without mutation.	Read-only inspection.

Project-ready branch choices:

Choice	Intent	Route
Single Agent Full Run	Build and operate one complete agent.	Tour guides; concrete setup, launch, gateway, mail, memory, inspection, and lifecycle work route to owning skills.
Operator-Controlled Agent Team	Build and manually control multiple complete agents.	Tour guides; per-agent setup and live operations route to owning skills.
Pro Agent Loop	Generate a loop from roles and topology.	Route generated loop construction to houmao-agent-loop-pro.
Subsystem Exploration	Inspect Houmao by component area.	Load branches/subsystem-exploration.md.

Welcome and Orientation

State	Welcome Shape
Blank slate	Short Houmao intro, current posture, likely Create Houmao Project path, Subsystem Exploration, and Inspect.
Existing state	One short acknowledgement, current posture, state-aware next choices.
Recent welcome already given	Skip welcome; continue from current posture.

Full blank-slate intro:

Welcome to Houmao. Houmao creates, runs, inspects, and coordinates CLI-based AI agents with managed runtime, gateway, mailbox, memory, and loop support.

Branches

Branch	Use
branches/orient.md	Current posture and stage-aware action table.
branches/fast-paths.md	Single Agent Full Run, Operator-Controlled Agent Team, Pro Agent Loop.
branches/subsystem-exploration.md	Component-minded subsystem exploration.
branches/quickstart.md	Old quickstart wording; prefer Single Agent Full Run for complete fast path.
branches/setup-project-and-mailbox.md	Project overlay or mailbox basics.
branches/author-and-launch.md	Specialist/profile authoring or launching another agent.
branches/live-operations.md	Prompt, memo, mailbox, notifier, gateway, reminder, inspection, manual coordination.
branches/advanced-usage.md	Loop-lite, loop-pro tree/generic mode, isolated workspace guidance.
branches/lifecycle-follow-up.md	Inspect, stop, relaunch, join/adopt, cleanup follow-up.

References

Reference	Use
references/question-style.md	User-input questions with required/optional fields and examples.
references/concepts.md	Short vocabulary: specialist, profile, managed agent, gateway, mailbox, notifier round, memory, loop, workspace, relaunch, cleanup.

Routing Guidance

Intent	Owning Skill
Project overlay setup/explanation	houmao-project-mgr
Mailbox root/account/admin	houmao-mailbox-mgr
Credential readiness/content	houmao-credential-mgr
Specialist/profile/launch dossier/easy launch	houmao-agent-definition
Runtime inspection/evidence	houmao-agent-inspect
Prompt/interrupt/raw input/mailbox-routing entry	houmao-agent-messaging
Gateway lifecycle/watch/mail-notifier/reminders	houmao-agent-gateway
Mail send/read/reply/post/archive	houmao-agent-email-comms
One gateway-notified open-mail round	houmao-process-emails-via-gateway
Memo/pages/memo seed	houmao-memory-mgr
Lite loop authoring/execution	houmao-agent-loop-lite
Pro loop authoring/topology/execution	houmao-agent-loop-pro
Isolated workspace planning/creation/validation	houmao-utils-workspace-mgr
Elemental coordination pattern	houmao-adv-usage-pattern
Stop/relaunch/join/adopt/list/cleanup	houmao-agent-instance

Present tree-loop and generic-loop as topology choices inside houmao-agent-loop-pro, not as separate skill packages.

Guardrails

Guardrail	Rule
Activation	Do not activate unless the user explicitly asked for touring.
Catalog	Do not turn the tour into a full packaged-skill catalog.
State	Never restart from project initialization when current state exists.
Order	Inspect current state before welcome selection for orientation and outcome requests.
Ownership	Do not claim direct-operation command shapes.
Commands	Do not invent top-level houmao-mgr easy ... or houmao-mgr specialists ...; reusable definitions live under houmao-mgr project ....
Lifecycle	Keep stop, relaunch, and cleanup separate; never auto-run cleanup after stop.
Loops/workspaces	Keep loop topology, run-control, direct-SQL, workspace, and elemental protocol details on owning skills.
Packaging	Keep packaged touring content self-contained; do not reference development-repository-only paths.