Salon_Assistant/CONTRIBUTING.md

Contributing

Before you code

1. Read design/DESIGN_PLAN.md.
2. Read design/use-cases.md, design/scenarios.md, design/DECISIONS.md.
3. Implementation requires an explicit build decision for greenfield features; structural and documentation work follows this CONTRIBUTING guide.
4. Coding agents must also follow AGENTS.md — especially Execution loop (mandatory) and Git hygiene (mandatory). Agents must run those rails without the user naming every step.

Platform-first

• Sandbox, policy, credentials, channels, inference: nemohermes / openshell only.
• Product scripts wrap those CLIs. Do not add a parallel control API.

Git ops for this product

Item	Value
Remote	Gitea Ty_Tech/Salon_Assistant
Default branch	main
Agent Git MCP	gitea_vps only (https://giteamcp1.vps1.afterthedemo.com/mcp, User-Agent grok-connectors-manager/)
Forbidden MCP	gitea_mcp_for_ty, localhost Git MCP for this product

Local git on a clone is fine for day-to-day status/diff/commit. Use gitea_vps for remote PR/branch operations against the product repo when working as an agent with MCP.

Branching

• Branch from current main.
• Prefer prefixes: docs/, design/, chore/, fix/, feat/.
• Keep branches focused; one concern per branch when practical.
• Do not force-push main. Do not rewrite published history without explicit coordination.

Commits

• No secrets in trees or messages (see SECURITY.md and .gitignore).
• Stage only files that belong to the change; review git status and the staged diff.
• Prefer small, reviewable commits with imperative subject lines and a short why when needed.
• Do not skip hooks (--no-verify) unless an operator explicitly requires it for a broken-hook emergency.
• Agents: commit/push only when the user asks (see AGENTS.md checklists).

Pull requests

• Base: main.
• Title reflects the change; body includes summary and how it was verified.
• Keep use-case SSOT in design/use-cases.md (do not duplicate full matrices in README).
• Run make verify when implementation exists (fixture CI).
• Agents open/update PRs via gitea_vps; merge only when the user asks.
• No secrets, tokens, or production PII in PR text.

Suggested PR body shape

## Summary
- …

## Verification
- [ ] … (e.g. docs-only review / make verify / doctor)

## Notes
- Related design decisions / use cases if any

Code style

• Python 3.11+ for skill scripts and providers.
• Deterministic logic in code; LLM only where the design matrix allows.

Releases

• Tag releases (vX.Y.Z).
• Pin images and MCP package versions in the release manifest.
• scripts/upgrade.sh is the operator upgrade entrypoint (see docs/UPGRADE.md).
• Changelog: CHANGELOG.md (Keep a Changelog).

Hygiene anti-patterns

Avoid	Prefer
Commit .env, keys, OAuth dumps	OpenShell providers / host env; examples only as .env.example
git add . without review	Explicit paths after git status / diff
Drive-by refactors in unrelated PRs	Separate branch/PR
Force-push to shared main	Revert commit or forward fix
Agent “cleanup” that deletes unknown user files	Investigate; ask before destructive clean