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”).

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

---

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
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 agent (or /execute-plan orchestrator) 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.
Workflows	Allowed for repeatable gates; must not bypass authorize/review/check/git hygiene. 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.

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.
• 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