Salon_Assistant/AGENTS.md

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
2. design/use-cases.md
3. design/scenarios.md
4. design/DECISIONS.md
5. docs/README.md (operator manuals)
6. Execution loop — default harness rails (plan → build → review → check → commit)
7. Git hygiene — binding for every agent session
8. 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. 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

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.

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.
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
• Human/agent PR conventions: CONTRIBUTING.md
• Short Grok rule mirror: .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)

[ ] 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

[ ] 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
• Security / no secrets in git: SECURITY.md
• Ignore patterns: .gitignore