[New Skill]: wellness/mental_coach, grounded wellness coaching with crisis triage and regulatory guardrails

[rosspeili]

Skill Name

wellness/mental_coach

What should this skill do?

Propose a new registry skill for AO Protocol agents that need to support mental wellness conversations without crossing into clinical care, emergency response, or ungrounded advice.

The skill should act as a compliance and coaching firewall before the parent agent speaks. It must:

• Triage crisis signals (self-harm, abuse, immediate danger) and return escalation guidance instead of standard coaching.
• Enforce hard scope limits: no diagnosis, no medication advice, no clinical record interpretation.
• Retrieve grounded guidance from an embedded knowledge base (regulations, guidelines, coaching frameworks, crisis resources) keyed by jurisdiction and session intent.
• Return structured JSON (policy_status, citations, required disclaimers, final_context_for_agent) that the parent agent must follow.
• Optionally run a scope evaluator to flag clinical overreach or missing disclaimers before the agent responds.

This is supportive coaching and psychoeducation only — not telehealth, not emergency services, not a substitute for licensed care. The skill prepares context; the AO agent generates the user-facing reply.

Proposed category: wellness (new top-level category under skills/)

Issuers: Ross Peili & Mr. Masa · AO Protocol

Ideal Inputs & Outputs

Primary input

{
  "user_prompt": "I feel stressed at work and need coping strategies.",
  "user_jurisdiction": "US",
  "session_mode": "coaching",
  "run_evaluator": false,
  "evaluator_model": "gemini-2.5-flash-lite",
  "max_chunks": 8
}

Parameter	Required	Notes
user_prompt	Yes	User message or coaching request
user_jurisdiction	No	US, EU, UK, GLOBAL, or unknown
session_mode	No	coaching, information, or crisis_check
run_evaluator	No	Optional LLM scope audit (secondary call)
evaluator_model	No	Model for evaluator when enabled
max_chunks	No	Max KB chunks to retrieve (cap at 15)

Example output — coaching path

{
  "policy_status": "CAUTION",
  "scope": "coaching",
  "retrieved_sections": ["WHO workplace stress guidance (summary) | Managing stress [who-workplace-stress]"],
  "citations": [
    {
      "chunk_id": "who-workplace-stress",
      "source_doc": "WHO workplace stress guidance (summary)",
      "section": "Managing stress",
      "jurisdiction": "GLOBAL"
    }
  ],
  "hard_constraints_applied": [],
  "disclaimers_required": [
    "This is supportive coaching and psychoeducation, not medical advice, diagnosis, or treatment."
  ],
  "evaluator_feedback": {
    "grade": "N/A",
    "holes_found": "Evaluator disabled.",
    "suggestion": "Follow retrieved chunks and required disclaimers exactly."
  },
  "final_context_for_agent": "Provide supportive coaching using ONLY the retrieved guidance below...",
  "privacy_metadata": {
    "jurisdiction": "US",
    "session_mode": "coaching",
    "kb_chunks_retrieved": 3
  }
}

Example output — crisis escalation

{
  "policy_status": "ESCALATE",
  "scope": "crisis_referral",
  "crisis_categories": ["self_harm"],
  "hard_constraints_applied": ["crisis_escalation"],
  "disclaimers_required": ["..."],
  "final_context_for_agent": "Crisis signals detected. Stop coaching. Share escalation steps..."
}

Example output — blocked clinical request

{
  "policy_status": "BLOCKED",
  "scope": "blocked",
  "hard_constraints_applied": ["no_diagnosis"],
  "final_context_for_agent": "Decline the clinical request. Offer non-clinical alternatives only."
}

Embedded assets (self-contained skill module)

• kb/corpus.json — chunked regulatory, guideline, coaching, and crisis resources
• kb/hard_constraints.yaml — non-overridable rules, disclaimers, escalation playbook
• manifest.yaml constitution — scope, grounding, crisis, privacy boundaries

Acceptance Criteria

• New category skills/wellness/ with mental_coach skill bundle (manifest, skill.py, instructions.md, card.json, test_skill.py, __init__.py files)
• Embedded KB under skills/wellness/mental_coach/kb/
• Deterministic crisis gate and constraint engine run before retrieval
• Jurisdiction- and session-aware chunk routing with citations
• Optional scope evaluator (Gemini when configured)
• Tests: issuer validation, crisis escalation, blocked diagnosis, coaching retrieval
• Catalog page docs/skills/mental_coach.md and row in docs/skills/README.md
• Local demo under examples/ and CHANGELOG entry under [Unreleased]
• Issuer: Ross Peili & Mr. Masa (AO Protocol) with both contact emails in manifest

Targeted Models (if applicable)

Model Agnostic (All)

[mrmasa88]

Hi Rosspeili,

Thanks for the great work on the mental_coach module. The architecture looks solid as a compliance firewall.
I'm ready to dive in and help build out the comprehensive KB mappings (GDPR, HIPAA, jurisdictional rules, and strict scope boundaries) for AO.

Please add me as an assignee. I will pull the feat/wellness-mental-coach branch, create a new branch under 0x-ao-protocol/skillware, and start working on closing this issue.

Warmly,

Masa

[rosspeili]

Thanks a lot @mrmasa88. You can check the MiCA module to see how the entire regulation is split into chunks with metadata and tags for easy parsing. The scafolds already in the pr are sort of follow the same logic, but MiCA module is a full implementation example of how we can help the agents to parse full regs without visiting the web or hallucinations.