diff --git a/.grok/rules/execution-loop.md b/.grok/rules/execution-loop.md index cc23214..3188585 100644 --- a/.grok/rules/execution-loop.md +++ b/.grok/rules/execution-loop.md @@ -14,13 +14,14 @@ Authorize → Plan (if needed) → Build → Review → Check → Local commit ( 1. **No product implementation** until the user says **build** or **implement**. Docs/design/agent-rules work is fine without that. 2. **Do not require the user to restate process.** If they authorize a slice, run plan (when needed) → build → independent review → check yourself. -3. **Review + check** on multi-file / non-trivial work. Prefer `/review --local` and `/check-work`. Equivalent: read-only reviewer subagent + verifier subagent / `make verify`. Same agent editing and saying “LGTM” is not enough. -4. **Commit only when asked.** **Never push, open/merge PR, or tag** unless the user explicitly orders it. User owns `git push` by default. -5. **Scope lock.** Implement only the authorized slice. No drive-by packages, no silent redesign of `design/` SSOT. -6. **Subagents:** implementers edit; reviewers/explorers/verifiers are read-only. Parallel writers use worktrees. Inject product hard rules into every implementer prompt. -7. **Multi-PR / execute-plan:** only with a PR Plan DAG; `--dry-run` first when using execute-plan; this product → no Graphite default, no auto-PR, no push/merge unless user overrides in writing. Remote MCP = **gitea_vps** only. -8. **Stop** when the slice is done, blocked on a user decision, or would require secrets / destructive git / forge mistakes — report, do not steamroll. -9. **Platform-first:** `nemohermes` / `openshell` only; no parallel control API; no owner terminal/Docker instructions; no agent pay / silent send. +3. **Grok parent = orchestrator only.** All product work (implement / review / check / explore / fix) runs on local **`wwg3-worker`** subagents. See `local-worker.md`. +4. **Review + check** on multi-file / non-trivial work via **worker** subagents (`model: "wwg3-worker"`). Prefer `/review` + `/check-work` patterns that spawn workers. Parent self-LGTM is not enough. +5. **Commit only when asked.** **Never push, open/merge PR, or tag** unless the user explicitly orders it. User owns `git push` by default. +6. **Scope lock.** Implement only the authorized slice. No drive-by packages, no silent redesign of `design/` SSOT. +7. **Subagents:** `model: "wwg3-worker"` always (unless user overrides). Implementers edit; reviewers/explorers/verifiers read-only. Parallel writers use worktrees. Inject product hard rules into every worker prompt. +8. **Multi-PR / execute-plan:** only with a PR Plan DAG; `--dry-run` first; no Graphite default, no auto-PR, no push/merge unless user overrides. Workers stay on `wwg3-worker`. Remote MCP = **gitea_vps** only. +9. **Stop** when the slice is done, blocked on a user decision, local worker is down, or secrets / destructive git / forge mistakes would be required — report, do not steamroll onto paid Grok. +10. **Platform-first:** `nemohermes` / `openshell` only; no parallel control API; no owner terminal/Docker instructions; no agent pay / silent send. ## Tiny exception diff --git a/.grok/rules/local-worker.md b/.grok/rules/local-worker.md new file mode 100644 index 0000000..c1e746d --- /dev/null +++ b/.grok/rules/local-worker.md @@ -0,0 +1,29 @@ +# Local worker + Grok orchestrator (mandatory) + +Full SSOT: `AGENTS.md` → **Orchestrator vs local worker (mandatory)**. + +## Split + +| Role | Model | Job | +|------|-------|-----| +| Parent session (composer) | Grok (`grok-4.5` / session default) | Orchestrate only | +| Every subagent / workflow child | **`wwg3-worker`** (local endpoint) | **All product work** | + +## Orchestrator MUST + +- Spawn workers with `model: "wwg3-worker"` for explore / plan / implement / review / check / fix. +- Inject product rails + authorized slice into every worker prompt. +- Sequence the execution loop; talk to the user; enforce no push unless asked. +- If local endpoint fails: **stop and report** — do not finish the work on paid Grok. + +## Orchestrator MUST NOT + +- Implement product code (`write` / `search_replace` / bulk codegen) in the parent when a worker should. +- Omit `model` / use cloud models for workers without an explicit user override for that task. +- Use the local worker as the parent orchestrator model. + +## Exceptions (parent only) + +Agent-rules edits (`AGENTS.md`, `.grok/rules/*`), pure Q&A, orientation reads, git inspect, local commit **when user asks**, kill/stop subagents, true one-line nits requested in-chat. + +When unsure → **delegate to `wwg3-worker`**. diff --git a/AGENTS.md b/AGENTS.md index 3ccaf1f..d20915b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,8 +27,8 @@ Also auto-loaded under `.grok/rules/`: `execution-loop.md`, `git-hygiene.md`. - 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”). - +- **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** (`wwg3-worker`). ## Git MCP - Server: `gitea_vps` @@ -38,6 +38,71 @@ Also auto-loaded under `.grok/rules/`: `execution-loop.md`, `git-hygiene.md`. --- +## 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) | **`wwg3-worker`** (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.wwg3-worker]` → LAN llama.cpp OpenAI-compatible URL +- `[subagents] default_model = "wwg3-worker"` +- `[subagents.models]` pins: `general-purpose`, `explore`, `plan` → `wwg3-worker` + +Optional Responses-API twin: `wwg3-worker-responses` — only if the orchestrator explicitly needs that backend. + +### 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 **`wwg3-worker`**. +2. **Pass `model: "wwg3-worker"`** 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: "wwg3-worker"` (or an explicit user override). +4. Use `wwg3-worker` 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 `wwg3-worker`**. + +### Worker spawn defaults + +```text +subagent_type: general-purpose | explore | plan # as needed +model: "wwg3-worker" # 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. @@ -69,15 +134,17 @@ If scope is unclear after **build**, ask **one** clarifying question or propose | Rule | Requirement | |------|-------------| +| Model | **Every** product subagent: `model: "wwg3-worker"`. 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 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. | +| 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 **`wwg3-worker`**. | +| 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 **`wwg3-worker`**. | ### Stop conditions (do not “push through”) @@ -93,6 +160,9 @@ Stop and report to the user when: ### Anti-rails (forbidden defaults) - Implementing product code because “we’re in execution mode” without **build** / **implement**. +- **Parent Grok implementing product work** instead of spawning `wwg3-worker`. +- 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.” diff --git a/CLAUDE.md b/CLAUDE.md index dbc96f2..a56ca42 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,9 +7,9 @@ This directory is the **Salon_Assistant / Lumina** product seed (Gitea `Ty_Tech/ 3. Operator docs live under `docs/`; do not treat them as a second design SSOT. 4. **No product implementation** until the user says **build** / **implement**. 5. **Default rails without being asked:** plan (if needed) → build authorized slice → independent review → check → commit only if asked → **no push** unless asked. -6. Git remote ops for this product: **`gitea_vps` only** — never `gitea_mcp_for_ty` or localhost Git MCP. -7. Platform-first: `nemohermes` / `openshell` only; no parallel control API. -8. Owner-facing answers must never include terminal, nano, or Docker instructions. -9. Subagents inherit these rules; reviewers/verifiers stay read-only; parallel writers use worktrees. - +6. **Grok parent orchestrates only.** All product work goes to local subagent model **`wwg3-worker`** (`spawn_subagent` with `model: "wwg3-worker"`). Do not implement product code in the parent. +7. Git remote ops for this product: **`gitea_vps` only** — never `gitea_mcp_for_ty` or localhost Git MCP. +8. Platform-first: `nemohermes` / `openshell` only; no parallel control API. +9. Owner-facing answers must never include terminal, nano, or Docker instructions. +10. Subagents inherit these rules; reviewers/verifiers stay read-only; parallel writers use worktrees. If any instruction conflicts, **this tree’s `AGENTS.md` wins** over parent workspace notes for product work inside `Salon_Assistant/`. diff --git a/README.md b/README.md index 37891b7..3c626a1 100644 --- a/README.md +++ b/README.md @@ -45,4 +45,4 @@ Code under `skills/`, `scripts/`, `services/`, `policy/`, etc. is **scaffold onl - Gitea: `Ty_Tech/Salon_Assistant` (public) - Git MCP for this product: **`gitea_vps`** only -- **Agents:** mandatory **execution loop** + **Git hygiene** in [`AGENTS.md`](AGENTS.md) (also `CLAUDE.md`, `.grok/rules/execution-loop.md`, `.grok/rules/git-hygiene.md`). Agents must follow the rails without the user restating process. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for branch/PR conventions. +- **Agents:** mandatory **execution loop**, **local-worker split** (Grok orchestrates; `wwg3-worker` does product work), and **Git hygiene** in [`AGENTS.md`](AGENTS.md) (also `CLAUDE.md`, `.grok/rules/*`). Agents must follow the rails without the user restating process. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for branch/PR conventions.