Ty
ce087533fa
Codify authorize → plan → build → review → check → local-only save so Grok Build stays on process without the user naming every slash command.
84 lines
3.4 KiB
Markdown
84 lines
3.4 KiB
Markdown
# 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 |
|