# Agent notes — Salon_Assistant / Lumina

## What this repo is

Product seed for a **NemoClaw + Hermes** salon/spa owner assistant.  
Remote: Gitea **Ty_Tech/Salon_Assistant** (via **gitea_vps** MCP only for this product’s Git ops).

## Read first

1. [`design/DESIGN_PLAN.md`](design/DESIGN_PLAN.md)  
2. [`design/use-cases.md`](design/use-cases.md)  
3. [`design/scenarios.md`](design/scenarios.md)  
4. [`design/DECISIONS.md`](design/DECISIONS.md)  
5. [`docs/README.md`](docs/README.md) (operator manuals)  
6. **[Execution loop](#execution-loop-mandatory)** — default harness rails (plan → build → review → check → commit)  
7. **[Git hygiene](#git-hygiene-mandatory)** — binding for every agent session  
8. [`CONTRIBUTING.md`](CONTRIBUTING.md) for PR/branch detail  

Also auto-loaded under `.grok/rules/`: `execution-loop.md`, `git-hygiene.md`.

## Hard rules

- **Platform-first:** `nemohermes` / `openshell` for config; no parallel control API.  
- **No build** until user says **build** / **implement**.  
- **No** `gitea_mcp_for_ty` / localhost Git MCP for this product — **gitea_vps** only.  
- Owner never gets terminal/nano/docker instructions.  
- No agent pay; no silent send/publish.  
- **`design/`** = product POR SSOT; **`docs/`** = operator runbooks.  
- **Execution loop + Git hygiene below are mandatory** for every agent (Grok, Claude, Cursor, subagents, workflows, scripts).  
- **Do not require the user to restate process.** If they authorize work without naming every step, still run the rails. Only the user may *narrow* scope or *skip* a gate (e.g. “docs-only, skip check-work”).  
- **Orchestrator / worker split** — see [Orchestrator vs local worker](#orchestrator-vs-local-worker-mandatory). Grok (composer) orchestrates only; **all product work runs on the local subagent endpoint** (`primary-subagent`).
## Git MCP

- Server: `gitea_vps`  
- URL: `https://giteamcp1.vps1.afterthedemo.com/mcp`  
- User-Agent: `grok-connectors-manager/`  
- Repo: **owner `Ty_Tech`**, **repo `Salon_Assistant`**, default branch **`main`**

---

## Orchestrator vs local worker (mandatory)

**Purpose:** conserve paid Grok tokens. The parent session is the **orchestrator**; heavy work runs on a **local** OpenAI-compatible endpoint.

| Role | Who | Model | Allowed to |
|------|-----|-------|------------|
| **Orchestrator** | Parent Grok Build session (composer) | Session model (e.g. `grok-4.5`) | Talk to user; authorize/scope; run the execution loop; spawn/resume/kill subagents; read results; enforce rails; **light** git status; report blockers |
| **Worker** | Every subagent (and workflow `agent()` children) | **`primary-subagent`** (display: **Primary Subagent**, local) | Explore, plan drafts, implement, review, check, fix, write files, run tests in scope |

### Config (already expected on this host)

Home `~/.grok/config.toml` (not committed to product git):

- `[model.primary-subagent]`  
  - `name = "Primary Subagent"`  
  - `base_url = "http://192.168.1.203:8083/v1"`  
  - `model` = GGUF id served by that endpoint (currently `…/Qwen3.6-27B-UD-Q4_K_XL.gguf`)  
- `[subagents] default_model = "primary-subagent"`  
- `[subagents.models]` pins: `general-purpose`, `explore`, `plan` → `primary-subagent`  
- **Removed:** stale `wwg3-worker` / `:8080` entries — do not reintroduce.

### Orchestrator MUST

1. **Delegate all product work** — implementation, multi-file edits, test writing, skill/script coding, substantive design drafting when authorized, independent review, and verification — via `spawn_subagent` (or workflow agents) on **`primary-subagent`**.  
2. **Pass `model: "primary-subagent"`** on every `spawn_subagent` for this product (belt-and-suspenders even when config pins exist). Do **not** pass `grok-4.5` / cloud models to workers unless the user **explicitly** overrides for that one task.  
3. **Stay coordinator-shaped:** status updates, sequencing, checklists, reading worker summaries, applying execution-loop gates, asking the user when blocked.  
4. **Inject full rails into every worker prompt:** authorized slice, hard rules, execution loop, Git hygiene, platform-first, no secrets, gitea_vps-only remote MCP.  
5. **Own Git policy** (commit only if asked; no push/PR/merge unless asked) even when workers make commits in worktrees.  
6. If the local endpoint is **down or failing**, **stop and report** — do not silently re-run the same workload on paid Grok “to finish.”

### Orchestrator MUST NOT

1. **Implement the product itself** with `write` / `search_replace` / large shell codegen on the main session when a worker can do it.  
2. “Just quickly” rewrite skills, services, scripts, or policy overlays in the parent after **build** is authorized — spawn a worker.  
3. Spawn workers **without** `model: "primary-subagent"` (or an explicit user override).  
4. Use `primary-subagent` as the **parent** session model for orchestration (parent stays Grok).  
5. Burn parent context by pasting entire file trees into chat when a worker can `read_file` / `grep` in a worktree.

### Allowed parent-session exceptions (small)

Parent Grok **may** do these without a worker:

- Answer questions; clarify scope; update **agent rails only** (`AGENTS.md`, `.grok/rules/*`, `CLAUDE.md`) when the user is changing process.  
- Single-line or pure typography nits the user asked for **in-chat** (still no unauthorized product build).  
- Read tools for orientation (`read_file`, `grep`, `list_dir`) to write a good worker prompt — not to replace the worker.  
- Git inspect (`status`/`diff`/`log`) and, **when the user asks**, a local commit of already-prepared work.  
- Emergency stop / kill runaway subagents.

If unsure whether something is “product work,” **delegate to `primary-subagent`**.

### Worker spawn defaults

```text
subagent_type: general-purpose | explore | plan   # as needed
model:         "primary-subagent"                      # always for this product
isolation:     "worktree" for parallel/implement writers; none for read-only explore/review when sharing tree is intended
capability:    read-only for review/explore; read-write or all for implement/fix
```

Prefix `description` with role tags when using skill patterns: `[implementer]`, `[reviewer]`, `[checker]`, etc.

### Workflows

Rhai/`workflow` child agents inherit the same rule: product work on **local worker**, not paid parent. Prefer pinning via host subagent defaults; if a workflow supports model opts, set the local worker explicitly.

---

## Execution loop (mandatory)

Default path for **any** non-trivial change. The user does **not** need to type each slash command; the agent **must still execute the gates**. Slash commands (`/plan`, `/review`, `/check-work`, `/execute-plan`, …) are preferred when available; equivalent manual steps (plan in chat, independent reviewer subagent, verifier subagent) are required if skills are not invoked by name.

```text
Authorize → Plan (if needed) → Build → Review → Check → Local commit (if asked) → User pushes
```

### Authorize (hard stop)

| User said… | Agent may… |
|------------|------------|
| **build** / **implement** (with or without slice) | Product implementation within stated or agreed slice |
| Design / docs / hygiene / scaffolding structure only | Edit design, docs, agent rules, README scaffolds — **not** product runtime code until **build** |
| Vague “continue” / “do it” **after** an approved plan or build slice | Continue **that** slice only; do not expand scope |
| Nothing authorizing build | **No** product implementation |

If scope is unclear after **build**, ask **one** clarifying question or propose a minimal slice and wait — do **not** invent a multi-package rewrite.

### Default gates (do these without being asked)

1. **Plan** — If approach is ambiguous or multi-file architecture is involved: enter plan mode / write a short plan and get approval **or** follow an existing approved plan/design section. Skip plan only for trivial single-concern edits (typo, one obvious fix).  
2. **Build** — Implement only the authorized slice. Prefer main session for one sequential change.  
3. **Review** — Independent review of the diff (prefer `/review --local`, else a **read-only** reviewer subagent). Address **bugs** before claiming done; suggestions/nits: fix or note wontfix with reason.  
4. **Check** — Verify work (prefer `/check-work`, else a verifier subagent / `make verify` when implementation exists). Do not mark complete on green review alone.  
5. **Save** — Commit **only** when the user asks (commit / checkpoint / prepare local commit). **Never push, open/merge PR, or tag** unless the user explicitly asks. User owns `git push` by default.

### Subagents & orchestration (rails, not free-for-all)

| Rule | Requirement |
|------|-------------|
| Model | **Every** product subagent: `model: "primary-subagent"`. Parent stays Grok. See [Orchestrator vs local worker](#orchestrator-vs-local-worker-mandatory). |
| Who codes | Workers implement/review/check. Parent does **not** implement product code. |
| Roles | **Implementers** edit; **reviewers/explorers/verifiers** are read-only (no source edits). |
| Isolation | Parallel writers → `isolation: "worktree"`. Do not parallel-edit the main tree. |
| Scope | One concern per implementer. No “implement half the product” prompts. |
| Product rules | Every implementer/reviewer prompt **must** include or inherit: this file’s hard rules, authorized slice, no secrets, platform-first, owner-safe messaging. |
| Resume | Fix cycles: `resume_from` same implementer/reviewer. After ~4 review-fix rounds, escalate disagreement to the user or refresh reviewer — do not thrash forever silently. |
| Orchestrator | Main Grok session (or `/execute-plan` orchestrator on Grok) owns sequencing, git policy, and user-facing status. Subagents do not push/merge. |
| Multi-PR | Only with an explicit PR Plan DAG (`## PR Plan` / `### PR N:`). Prefer `/execute-plan --dry-run` first. This repo: **`--no-graphite`**, **no auto-PR**, **no push/merge** unless user overrides in writing. Implementers/reviewers still **`primary-subagent`**. |
| Workflows | Allowed for repeatable gates; must not bypass authorize/review/check/git hygiene. Child agents = local worker. Effectful git still needs user-gated commit/push rules above. |
| best-of-n | Only when user asks or two architectures must be compared with a clear eval; candidates on **`primary-subagent`**. |

### Stop conditions (do not “push through”)

Stop and report to the user when:

- Authorized slice is done (review + check clean, or issues listed).  
- Build was never authorized.  
- Plan is blocked on a product decision only the user can make.  
- Review/check finds **bugs** you cannot fix without expanding scope.  
- Secrets, destructive git, or forge mismatch (GitHub/`gh` assumptions on this Gitea product) would be required.  
- Subagent wants to rewrite `design/` SSOT or add a parallel control API.

### Anti-rails (forbidden defaults)

- Implementing product code because “we’re in execution mode” without **build** / **implement**.  
- **Parent Grok implementing product work** instead of spawning `primary-subagent`.  
- Spawning subagents on paid/cloud models for product work without explicit user override.  
- Silently falling back to Grok when the local worker is down.  
- Skipping review **and** check on a multi-file change.  
- Self-only review (same agent edits and declares “LGTM” with no independent pass).  
- Push/PR/merge/tag as a surprise side effect of “finishing.”  
- Expanding into neighboring packages/skills “while here.”  
- Using GitHub/`gh`/Graphite flows as defaults on this Gitea product.  
- Weakening these rules in a subdirectory `AGENTS.md` or subagent prompt.

### Tiny-change exception

Single-file or pure typo/docs nit: plan optional; still **no push**; still no secrets; still no build without authorize. Prefer a quick diff self-check; full `/review` + `/check-work` strongly recommended once tests/scripts exist.

### Related

- Git details: [Git hygiene](#git-hygiene-mandatory)  
- Human/agent PR conventions: [`CONTRIBUTING.md`](CONTRIBUTING.md)  
- Short Grok rule mirror: [`.grok/rules/execution-loop.md`](.grok/rules/execution-loop.md)

---

## Git hygiene (mandatory)

Every agent that opens or works in this workspace **must** follow these practices. Deeper dirs inherit this file; do not weaken these rules in subdirectory `AGENTS.md` files.

### Identity of the remote

| Item | Value |
|------|--------|
| Hosted remote | Gitea `Ty_Tech/Salon_Assistant` |
| Default branch | `main` |
| Agent Git / PR MCP | **`gitea_vps` only** |
| Forbidden | `gitea_mcp_for_ty`, localhost Git MCP, inventing a second product remote |

Prefer local `git` for status/diff/commit/branch on the workspace clone; use **`gitea_vps`** for remote PR/branch/file ops against the product repo when MCP is appropriate. Never mix this product’s Git ops onto another MCP server.

### Never (unless the user explicitly orders that exact action)

| Action | Why |
|--------|-----|
| `git config` (any scope) | Do not change user or repo identity/settings |
| Commit or push **secrets** | `.env`, tokens, keys, OAuth dumps, provider credentials, PII exports |
| Force-push to `main` (or rewrite its history) | Shared default branch is protected by practice |
| `--force` / `--force-with-lease` push without explicit ask | Easy to destroy remote work |
| `--no-verify` / skip hooks | Hooks exist to catch mistakes |
| Amend a commit already pushed | Rewrites shared history |
| `reset --hard`, `clean -fd`, branch delete on remote | Destructive; confirm first |
| Push, open/merge PR, or tag release without user request | Shared/remote side effects need intent |
| Commit unrelated dirty files “while you’re at it” | Keeps history reviewable |
| Commit build artifacts, caches, venvs, logs, local IDE noise | Belongs in `.gitignore` |
| Paste secrets into commit messages, PR bodies, or issues | Transcripts and remotes leak |

### Always

1. **Orient before mutating Git:** `git status`, `git diff` / `git diff --staged`, and recent `git log` (e.g. `git log -5 --oneline`) so commits match repo style.  
2. **Work on a branch** for anything beyond a trivial single-commit fix the user asked to land on `main`. Prefer names:  
   - `docs/…`, `design/…`, `chore/…`, `fix/…`, `feat/…`  
   - Base new branches on up-to-date `main` when practical.  
3. **Stage only intended paths** (`git add <paths>`). Never `git add -A` / `git add .` without reviewing the full set.  
4. **Scan the staged diff for secrets** before every commit (`.env*`, keys, tokens, cookies, private URLs with credentials).  
5. **Commit only when the user asks** to commit/save/checkpoint (or an explicit workflow that includes commit).  
6. **Commit messages:** concise focus line in imperative mood; 1–3 sentences of *why* when non-obvious. Match existing history tone. No secret data. No noisy AI trailer spam unless the user asks for a trailer.  
7. **Push only when the user asks.** Prefer upstream tracking (`-u`) on first push of a branch.  
8. **PRs via `gitea_vps`:** base `main`, clear title/body (summary + test plan / how verified), draft/WIP when incomplete. Do not merge unless asked.  
9. **Confirm before destructive or shared-visible actions:** force-push, hard reset, remote branch delete, PR merge/close, rewriting published commits, mass file deletes.  
10. **Leave the tree honest:** do not hide failures by amending away broken intermediate state the user still needs; do not discard uncommitted user work.  
11. **Respect “no build”:** do not commit product implementation until **build** / **implement** is authorized; docs/design/scaffold hygiene changes are fine when requested.  
12. **Subagents inherit these rules.** When spawning agents, point them at this file or restate: no secrets, no force to `main`, no push/PR/merge without user ask, `gitea_vps` only for product remote Git MCP.

### Commit checklist (before `git commit`)

```text
[ ] User asked to commit (or workflow explicitly includes commit)
[ ] Branch is correct (not accidental detached HEAD / wrong fork)
[ ] git status + staged diff reviewed; only intended files staged
[ ] No secrets, credentials, owner PII, or local absolute machine dumps
[ ] No caches/venv/logs/state that should be gitignored
[ ] Message explains purpose; matches repo style
[ ] Hooks will run (do not pass --no-verify)
```

### Push / PR checklist

```text
[ ] User asked to push and/or open PR
[ ] Branch name is descriptive
[ ] Remote is origin → Ty_Tech/Salon_Assistant (Gitea)
[ ] PR uses gitea_vps; base = main
[ ] Description states what/why and how checked
[ ] No secrets in PR text or screenshots paths
```

### Recovering from mistakes

- Unstaged junk → restore files carefully; never `clean -fd` without listing what will die and getting confirmation.  
- Bad unpushed commit → amend only if HEAD is yours, not pushed, and user wants amend; otherwise new commit or interactive fix with consent.  
- Secret committed → **stop**; do not keep pushing. Tell the user; rotate credentials; remove from history only with explicit coordinated procedure (not casual `push --force` to `main`).

### Related docs

- Branch/PR conventions: [`CONTRIBUTING.md`](CONTRIBUTING.md)  
- Security / no secrets in git: [`SECURITY.md`](SECURITY.md)  
- Ignore patterns: [`.gitignore`](.gitignore)