Add wellness/mental_coach skill resolving #148

[mrmasa88]

Summary

Adds a new universal wellness/mental_coach skill that resolves #148.

It is a deterministic compliance + coaching firewall a parent agent calls before
generating wellness replies: it triages crisis signals first, enforces non-clinical
scope limits, retrieves grounded KB chunks with citations, optionally runs a scope
evaluator, and returns structured JSON (policy_status, citations,
disclaimers_required, final_context_for_agent, ...).

This is the generic, PyPI-shippable base skill — generic enough for any operator,
with no org-specific overlay mixed in.

Fixes #148

Type of change

• New skill

What's included

• skills/wellness/mental_coach/ full bundle: manifest.yaml, skill.py,
  instructions.md, card.json, test_skill.py, __init__.py
• Modular logic: crisis_gate.py, constraints.py, kb_provider.py, resources.py
• Embedded KB under kb/: corpus.json, hard_constraints.yaml, crisis_resources.json
• Catalog page docs/skills/mental_coach.md + new Wellness row in docs/skills/README.md
• examples/mental_coach_demo.py + examples/README.md row
• CHANGELOG.md [Unreleased] entry
• New category wellness/ (proposed in [New Skill]: wellness/mental_coach, grounded wellness coaching with crisis triage and regulatory guardrails #148; flagging for maintainer confirmation)

Safety design

• Deterministic crisis gate runs FIRST, before retrieval, with no LLM dependency.
• Biased to over-escalation: on a crisis signal, policy_status = ESCALATE, coaching
  is suppressed (no retrieval), and jurisdiction-appropriate crisis resources are returned.
• Hard constraints block diagnosis / medication / clinical interpretation, and resist
  prompt-injection attempts.
• Negation handling routes ambiguous phrasing to CAUTION rather than OK.
• EN-first v0.1: non-English input is routed to CAUTION + resources rather than passed silently.
• Crisis resources are real, source-verified public-safety data (US/UK/FR/DE/ES/IT/EU/GLOBAL)
  with 24/7 flags.

Skill checklist

• skills/wellness/mental_coach/ exists with full bundle
• manifest.yaml: name, version, description, parameters, constitution, real issuer
• skill.py: deterministic, JSON-serializable returns, safe error handling
• instructions.md: when to use, how to interpret output, limitations
• card.json issuer matches manifest
• test_skill.py passes (crisis ESCALATE, blocked diagnosis, injection, coaching retrieval, non-EN CAUTION)
• docs/skills/mental_coach.md + catalog row in docs/skills/README.md
• Usage Examples (Gemini, Claude, OpenAI, DeepSeek, Ollama) on the catalog page
• pytest tests/test_skill_issuer.py passes
• SkillLoader.load_skill("wellness/mental_coach") works
• examples/README.md updated
• No placeholders under skills/
• CHANGELOG.md updated under [Unreleased]

Tests

• black . clean, flake8 . clean
• pytest skills/ — 85 passed
• pytest tests/ — 76 passed
• pytest skills/wellness/mental_coach/test_skill.py + tests/test_skill_issuer.py — 12 passed
• Local demo: coaching OK, crisis ESCALATE (988 surfaced), clinical request BLOCKED

Issuer

Issuer is set to me (mrmasa88, AO) with my real contact email. Settled per maintainer confirmation.

[rosspeili]

Thanks for this @mrmasa88, exceptional work on 148.

Before merge, please:

1. Issuer, [New Skill]: wellness/mental_coach, grounded wellness coaching with crisis triage and regulatory guardrails #148 calls for Ross Peili & Mr. Masa (AO Protocol) with both real contact emails in manifest.yaml. Right now only your noreply GitHub email is set. Please align issuer in manifest.yaml, card.json, docs/skills/mental_coach.md, and docs/skills/README.md (happy to pair on exact wording). You don't need to add me, as I offered the scafold so you could work on it, add just your name / gh username and real email, not github no reply, as it will fail CI tests and be rejected.

Optional but appreciated in the same push:

2. Load full manifest.yaml in skill.manifest (same pattern as pdf_form_filler / recent wallet_screening fix).
3. Add wellness to the skill categories table in CONTRIBUTING.md.

Once the issuer most importantly is sorted, we should be good to merge, but you can include the housekeeping tweaks above too in the same pr. Nice and careful skill for a sensitive domain overall. Well done <3

[mrmasa88]

Hi @rosspeili . Thanks for your review and feedback.

Updated PR #174 with both of your points:

1. Issuer/contact is now my real email across the manifest, card, and docs — no more github no-reply.
2. Added a health/mental-health disclaimer on the catalog page, using hendobox / rizzoMartin as reference.

Git author stays clean (just me, no AI co-authors). Whenever you have a moment to re-review, much appreciated.

[rosspeili]

Thanks again @mrmasa88, the follow-up commit addresses the issuer blocker cleanly.

Yet, before we merge, please:

1. Sync with current main and resolve the CHANGELOG.md conflict

Your branch is behind upstream (main now includes #180 / #86 test layout and #173 wallet_screening fixes). Recommended path:

git fetch https://github.com/ARPAHLS/skillware.git main
git checkout feat/issue-148-wellness-mental-coach
git rebase FETCH_HEAD
# or: git merge FETCH_HEAD

When CHANGELOG.md conflicts under [Unreleased], keep all sections, do not drop upstream entries. Target shape:

## [Unreleased]

### Added
- **`wellness/mental_coach`**: … (#148).

### Changed
- **Tests**: Moved `tests/test_mica_module.py` to `tests/skills/compliance/…` (#86).
- **`wellness/mental_coach`**: Set real issuer contact email and add health disclaimer… (your follow-up).

### Fixed
- **`finance/wallet_screening`**: … (#173).

Then push:

git push --force-with-lease

(Use a normal git push instead if you merged rather than rebased.)

2. Housekeeping (same push if you can)

• Load full manifest.yaml in MentalCoachSkill.manifest (same pattern as wallet_screening / pdf_form_filler).
• Add wellness to the skill categories table in CONTRIBUTING.md.
• Add a wellness/mental_coach row to docs/usage/agent_loops.md (mental_coach_demo.py as local execute; provider columns → catalog page).
• Update the PR description, remove the stale “Ross Peili as primary issuer” note, as issuer is settled with your real mail.

3. Re-verify after rebase if want

python -m flake8 .
pytest skills/wellness/mental_coach/test_skill.py
pytest tests/test_skill_issuer.py
pytest skills/ tests/

Once that’s in, we should be good to merge. Optional later: a short Testing block on docs/skills/mental_coach.md, not blocking for this initial pr.

Again, super clean work on a sensitive domain like mental health, appreciate the careful crisis-first design. <3 Let me know if you need help or direction.

[mrmasa88]

Hi @rosspeili

All set on #174, V — addressed everything before merge:

1. Synced with upstream main (merge, not rebase) and resolved the CHANGELOG conflict under [Unreleased], keeping all sections — your [Feat]: Standardise two-tier test layout and document skill-local vs integration test convention #86 (tests move) and [Docs]: Align wallet_screening examples and docs with manifest tool name (finance/wallet_screening) #173 (wallet_screening) entries are intact alongside ours.
2. Housekeeping: MentalCoachSkill now loads the full manifest.yaml (wallet_screening / pdf_form_filler pattern); added wellness to the CONTRIBUTING categories table; added the wellness/mental_coach row to docs/usage/agent_loops.md; and updated the PR description (removed the stale issuer note — issuer is settled with my real email).

Locally clean: black, flake8, pytest skills/ tests/ = 161 passed. Branch shows no conflicts with base, git author is clean (just me, no AI co-authors).

One thing on the Checks tab: the workflows show "completed with no jobs" (Checks 0) — looks like CI didn't actually run jobs on the fork PR. Is there an approve-and-run step on your side, or a config I should be aware of? Happy to adjust if anything's needed. Otherwise it should be good for your review/merge. Thanks again for the guidance through this. <3

[rosspeili]

Great job @mrmasa88, reviewing now, yes the first CI for new contributors will be triggered manually once the pr looks good, after that, all your PRs will automatically trigger CI. I will trigger now and if it's green will merge <3

[rosspeili]

@mrmasa88 merged the new skill, issues new release 0.3.7 that includes it in pypi, so net pip install skillware or --update should include it, you can test it manually with different models to see how the skill performs, and adjust further for private, local use. You can also find it on the updated skillware.site library and docs. Congrats on seeing this through, this is a huge and delicate first contribution, not just cause it introduces a new category and new skill, but also cause the topic is thin. <3