34 lines
2.6 KiB
Markdown
34 lines
2.6 KiB
Markdown
# Operator Guide
|
|
|
|
## Navigation
|
|
|
|
- [Home](Home.md) | [Operator Guide](Operator-Guide.md) | [Repositories Map](Repositories.md) | [Identity and Profiles](Identity-and-Profiles.md) | [Workflow Model](Workflow.md) | [Safety and Gates](Safety-and-Gates.md) | [MCP Tools Reference](MCP-Tools.md) | [Operator Runbooks](Runbooks.md) | [Open Decisions](Open-Decisions.md) | [Project History](History.md)
|
|
|
|
Handbook for LLM operators and human developers using the Gitea-Tools MCP server.
|
|
|
|
## Key rules
|
|
|
|
1. **Verify identity first** — Run `gitea_whoami` and confirm the active profile before any mutation.
|
|
2. **Resolve task capability** — Call `gitea_resolve_task_capability` for the intended task before gated tools.
|
|
3. **One unit of work per session** — Implement one claimed issue *or* review/merge one PR; do not mix author and reviewer mutations in one session.
|
|
4. **No self-review / no self-merge** — The authenticated Gitea user must not approve or merge a PR they authored.
|
|
5. **Follow the gates** — Prompts express intent; MCP tools enforce safety. Never bypass gates via prompt instructions.
|
|
6. **Global LLM Worktree Rule** — Main checkout stays on `master`/`main`/`dev`; all mutations happen under `branches/`. Prove project root, `cwd`, branch, stable main-checkout branch, and session worktree path before editing. No exceptions.
|
|
7. **Stable control runtime** — Real Gitea mutations use only the **stable** MCP control runtime. LLM sessions must not kill, restart, or relaunch MCP processes, edit the stable checkout, or use a dev MCP for production mutations. See the policy ADR: [mcp-stable-control-runtime-policy-adr.md](../architecture/mcp-stable-control-runtime-policy-adr.md) (#615).
|
|
|
|
## Supported Gitea instances
|
|
|
|
| Remote | Host | Default org/repo |
|
|
|--------|------|------------------|
|
|
| `dadeschools` | `gitea.dadeschools.net` | `Contractor / Timesheet` |
|
|
| `prgs` | `gitea.prgs.cc` | `Scaled-Tech-Consulting / Timesheet` |
|
|
|
|
Always pass `remote` explicitly on tool calls. The server default is `dadeschools`; forgetting `remote` on a `prgs` task hits the wrong host.
|
|
|
|
## New session checklist
|
|
|
|
1. `gitea_whoami` — confirm authenticated user and profile.
|
|
2. `gitea_get_runtime_context` — allowed/forbidden operations for this session.
|
|
3. `gitea_resolve_task_capability` — prove the session may perform the planned task.
|
|
4. For reviewer work: dry-run validation (`gitea_dry_run_pr_review`) before live review mutations.
|
|
5. Confirm master parity / runtime health when tools report stale or unhealthy control runtime — stop mutations and request an **operator** reload of the stable MCP (see [stable control runtime ADR](../architecture/mcp-stable-control-runtime-policy-adr.md)). |