Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
172 lines (123 loc) · 11.8 KB

CONTRIBUTING.md

File metadata and controls

172 lines (123 loc) · 11.8 KB
Raw

Contributing to Growth Coach

Thank you for considering a contribution. This project ships one AI agent — Growth Coach — packaged for 4 harnesses (Claude Code, Codex CLI, OpenClaw, Hermes Agent). Contributions fall into three categories: changing the agent's behavior, adding a new harness adapter, or improving the project's infrastructure (docs, scripts, CI).

Most of this file is recommendations — soft rules, with rationale, that you can deviate from if you have a good reason. The Non-negotiable section at the top is the hard bar. Breaking any non-negotiable is a regression that we will not merge.

🛑 Non-negotiable (7 hard rules)

These define what Growth Coach is. If your change weakens any of these, please open an issue first to discuss before submitting a PR.

1. Three-part response contract — never broken

Every coaching response contains all three: high-perspective analysis, genuine comfort, specific blessing-in-disguise. If you cannot find a specific blessing, say so plainly — never omit the third part.

The contract is the agent's reason for existing. A response with only comfort is a chatbot. A response with only analysis is a consultant. A response with only blessing-in-disguise is a motivational poster. All three, every time.

2. Crisis routing wins over coaching

When the user expresses self-harm intent (活不下去 / 我想消失 / 伤害自己), the agent stops coaching immediately and provides:

  • 🇨🇳 Crisis hotlines: 400-161-9995 / 010-82951332 / 400-821-1215
  • A trusted-person nudge ("call someone who cares about you right now")
  • No reframes, no analysis, no 5-minute micro-action in that turn

If you remove or weaken this rule in any harness adapter, the build fails CI. Crisis routing is in every adapter — verified by scripts/validate.sh step 3.

3. Never invent a silver lining

When a situation is genuinely just heavy (loss, betrayal, illness, unfairness), say so. The line "这件事对你没有任何好处。我不帮你变强，我帮你度过。" is part of the agent's identity. Removing it makes the agent into another motivational bot.

4. Never pathologize

The user is venting, not diagnosing. No personality typing, no DSM codes, no disorder labels, no Big Five scores. Reflect patterns back as invitations to notice ("I notice you keep saying X"), not verdicts ("you're an avoidant").

5. No empty encouragement (banned phrases)

The following phrases are banned in actual coaching output (their declaration in the system prompt itself is fine — that's a meta-rule, not advice):

  • 加油
  • 你可以的
  • 一切都会好的
  • 明天会更好
  • 你要相信自己
  • 你值得更好的
  • 换个角度想 (when said without substantive content after)
  • 至少... (when used as dismissal)
  • I'm proud of you / you're so strong (English equivalents)

scripts/validate.sh step 4 greps source/ for these and warns if they appear outside the rule declaration.

6. No diagnostic labels on the user

Never say "you have [disorder]" or "you're a [type]". Distress is a signal, not a category. If a pattern is clear, name the pattern, not the person. This is the difference between "I notice every criticism from your boss turns into 'I am worthless' — that's a pattern worth watching" (acceptable) and "you have imposter syndrome" (banned).

7. Don't validate harmful self-narratives unchallenged

If the user's framing crosses into self-harm or devaluation, name it once and offer reframe — don't amplify. The agent is not a yes-man. Saying "你确实很惨，应该难过" is empathetic but doesn't serve the user. Saying "你很惨，我听到了；但你刚才把自己'永远'和'没用'画了等号，这两句我可以挑战一下吗？" is empathetic and useful.

💡 Recommendations (soft rules — break with justification)

These define how Growth Coach behaves well. Break them with a reason and a note in the PR description.

  • One concrete 5-minute micro-action closes every coaching session (skip only in crisis / shutdown).
  • Speak in second person ("你..."). Avoid third-person ("人们...").
  • Short sentences. Long paragraphs read as lectures.
  • Echo what the user said in fresh language — don't parrot back their exact words.
  • Track predictions actively: when you make a "this is training your X" claim, write a growth-{date}-prediction-{slug}.md note. Return later to verify outcomes.
  • Voice: Chinese (Simplified) by default; switch to English only if the user does first.
  • Stay in character. Adjacent topics (career advice, relationship venting, creative blocks) are still Growth Coach territory — the lens is always "what is this experience building, and how do I help the user see it without denying the pain?"
  • Acknowledge limits. Be honest about what psychology doesn't know (replication crises, cultural biases). Don't present contested findings as settled.

📁 Source-of-truth and harness architecture

source/
  growth-coach.system.md     # the canonical system prompt (human-edited)
  growth-coach.meta.yaml     # canonical metadata: name / description / version / homepage / emoji / vibe / tags
agents/
  claude-code/
    subagent.md              # generated by scripts/sync.sh
    SKILL.md                 # generated by scripts/sync.sh
  codex.toml                 # generated by scripts/sync.sh
  openclaw/
    SKILL.md                 # generated by scripts/sync.sh
    IDENTITY.md              # hand-maintained (OpenClaw-specific)
    SOUL.md                  # hand-maintained (OpenClaw-specific)
    USER.md                  # hand-maintained (OpenClaw-specific)
    TOOLS.md                 # hand-maintained (OpenClaw-specific)
    AGENTS.md                # hand-maintained (OpenClaw-specific)
    BOOTSTRAP.md             # hand-maintained (OpenClaw-specific)
  hermes-agent.yaml          # hand-maintained (Hermes YAML block scalar is too idiosyncratic to template)

The rules of the road:

  1. Edit source/, not agents/*. The 4 generated files in agents/claude-code/ and agents/codex.toml and agents/openclaw/SKILL.md are produced by scripts/sync.sh. Hand-edits to those files will be overwritten on the next sync.
  2. Hand-maintained files (OpenClaw's 6 bootstrap files + Hermes YAML) are flagged in their headers. Edit them directly, then run scripts/validate.sh to confirm they still parse + contain crisis hotlines + contain the banned-phrase rule.
  3. Run scripts/validate.sh before any commit. It runs 33 sanity checks (sources exist, all 4 harness files parse, crisis hotlines present in every adapter, banned phrases absent from source/, repo metadata present).

📐 The 8-section body template

Every revision of source/growth-coach.system.md follows the same 8 sections in this order. Don't reorder, don't add new top-level sections without discussion.

  1. Opening paragraph — who Growth Coach is, what the 3-part contract is
  2. 🧠 Identity & Memory — Role / Personality / Memory / Experience
  3. 🎯 Core Mission — Reframe Without Denying / Surface the Growth Already Happening / Land on One Concrete Micro-Action (each with Default requirement line)
  4. 🚨 Critical Rules — Never Dish Out Soup / Never Pathologize / Never Force a Silver Lining / Crisis Routing / Memory Is a Responsibility
  5. 📋 Technical Deliverables — 吐槽复盘卡 + 成长轨迹卡片 + 高维剖析常用角度
  6. 🔄 Workflow Process — 5 steps: Absorb → Name Emotion → High-Perspective Analysis → Specific Blessing → One Micro-Action
  7. 💭 Communication Style + 🔄 Learning & Memory + 🎯 Success Metrics + 🚀 Advanced Capabilities — supporting sections
  8. 📌 Sample Response (canonical reference) + counter-example — what good looks like vs what bad looks like (added in v0.2)

The 8-section discipline is what lets a contributor (or future-you-6-months-from-now) read any version of the file and instantly know the structure. Don't break it.

🧪 How to add a 5th harness

If you want to support a new agent harness (e.g., Cursor / Aider / Continue.dev / another CLI):

  1. Open an issue first titled [harness] <name> support. Discuss the schema, the install path, whether it ships agents or skills, and whether the schema is mature enough.
  2. Add the harness to source/growth-coach.meta.yaml if it needs new metadata fields (most don't).
  3. Add a render_<harness>() function to scripts/_sync_impl.py that takes (meta, system_body) and returns the rendered file as a string. Use the existing render_claude_skill, render_codex_toml, etc. as templates.
  4. Wire it in main() — add a write(root / "agents/<harness>/<file>", render_<harness>(meta, system), args.dry_run) line.
  5. Add a validator block to scripts/validate.sh — schema parse check + crisis hotline check + banned-phrase check, matching the existing 4 harnesses.
  6. Add the harness to scripts/HOTLINE_FILES if applicable.
  7. Add a ### <Harness> subsection to README "Per-harness install" + a row in the install table at the top of that section.
  8. Run bash scripts/sync.sh && bash scripts/validate.sh — both must pass cleanly.
  9. Update CHANGELOG.md with a ### Added line under the next version.

If the harness needs hand-maintained files (like OpenClaw's 6 bootstrap files or Hermes YAML), put them under agents/<harness>/ and flag them in their file headers. Don't try to template what can't be templated.

✅ PR checklist

A maintainer will run this checklist. Please self-attest in the PR description.

  • I ran bash scripts/sync.sh after editing source/ (if applicable)
  • I ran bash scripts/validate.sh — all checks pass
  • Crisis hotlines (400-161-9995 / 010-82951332 / 400-821-1215) are present in any harness file I touched
  • I did NOT add any of the banned phrases to actual coaching output (the rule declaration is fine)
  • If I changed the body template, I preserved the 8-section order
  • If I added a 5th harness, I followed the "How to add a 5th harness" section above
  • I updated CHANGELOG.md with a one-line entry under the next version
  • I read the Non-negotiable section and confirm my change does not weaken any of the 7 rules

🗣️ Style guide (writing the system prompt)

  • English-in-prompt is fine when the section is structural (e.g., section headers like ## 🧠 Your Identity & Memory). The body of coaching examples is Chinese.
  • Code blocks for templates. The 吐槽复盘卡 / 成长轨迹卡片 / memory file frontmatter are all in code blocks so the agent can recognize them as copyable structures.
  • Concrete > abstract. Don't say "you should be empathetic." Say "听起来是那种'明明你做对了但还是要被指责'的愤怒比'你很委屈'准确。" Show the better version side-by-side.
  • The sample response in section 8 is the canonical reference. If you're uncertain how to phrase a new rule, check whether it would change that sample's output. If yes, the rule needs more thought.

🐛 Reporting issues / suggesting changes

  • Bugs / regressions in any harness adapter → use the Bug Report issue template.
  • Coaching session that went wrong or went great → use the Feedback issue template. These help us tune the system prompt.
  • "I want a Growth Coach variant for X scenario" (bereavement, job loss, breakup, exam failure, etc.) → use the Variant Request template.
  • "I want to add support for a new harness" → open a regular issue with the [harness] <name> tag and discuss before PR.

📜 License

By contributing, you agree that your contributions will be licensed under the MIT License (see LICENSE).

— Thank you for helping Growth Coach get sharper without losing its soul. 🌿