# Contributing

## Before you code

1. Read [design/DESIGN_PLAN.md](design/DESIGN_PLAN.md).
2. Read [design/use-cases.md](design/use-cases.md), [design/scenarios.md](design/scenarios.md), [design/DECISIONS.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](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](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

```markdown
## 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](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 |