From b2263b0a9f14274cccbb17ac2c3cb23ecfeb707c Mon Sep 17 00:00:00 2001 From: NagyVikt Date: Wed, 22 Apr 2026 01:22:43 +0200 Subject: [PATCH] Keep small Guardex tasks on caveman-only routing by default Guardex installs a managed AGENTS block into downstream repos, but it did not tell agents when to stay lightweight versus when to escalate into OMX orchestration. This change adds a task-size routing clause to the managed template so small asks stay direct and caveman-only while larger cross-cutting work still has an explicit OMX path. Constraint: Guardex owns the managed AGENTS block, so the durable fix must live in the template and setup/doctor refresh coverage rather than repo-local docs only Rejected: Add a second Guardex-side runtime classifier | would duplicate OMX task-size heuristics and drift from the existing advisory detector Confidence: high Scope-risk: narrow Directive: Keep the managed Guardex AGENTS routing aligned with OMX task-size guidance when heavy-mode keywords or lightweight escape hatches change Tested: targeted install AGENTS refresh tests Tested: openspec change validation strict Not-tested: fresh downstream repo end-to-end after rerunning gx setup or gx doctor --- .../proposal.md | 12 ++++++++++ .../specs/guardex-task-size-routing/spec.md | 22 +++++++++++++++++++ .../tasks.md | 20 +++++++++++++++++ templates/AGENTS.multiagent-safety.md | 3 +++ test/install.test.js | 6 +++++ 5 files changed, 63 insertions(+) create mode 100644 openspec/changes/agent-codex-auto-route-small-tasks-to-caveman-and-la-2026-04-22-01-20/proposal.md create mode 100644 openspec/changes/agent-codex-auto-route-small-tasks-to-caveman-and-la-2026-04-22-01-20/specs/guardex-task-size-routing/spec.md create mode 100644 openspec/changes/agent-codex-auto-route-small-tasks-to-caveman-and-la-2026-04-22-01-20/tasks.md diff --git a/openspec/changes/agent-codex-auto-route-small-tasks-to-caveman-and-la-2026-04-22-01-20/proposal.md b/openspec/changes/agent-codex-auto-route-small-tasks-to-caveman-and-la-2026-04-22-01-20/proposal.md new file mode 100644 index 0000000..aab6912 --- /dev/null +++ b/openspec/changes/agent-codex-auto-route-small-tasks-to-caveman-and-la-2026-04-22-01-20/proposal.md @@ -0,0 +1,12 @@ +## Why +Guardex installs a managed AGENTS block, but it does not currently tell downstream repos when to stay lightweight versus when to invoke heavier OMX orchestration. That makes small asks burn unnecessary orchestration tokens even when Caveman/direct mode is enough. + +## What Changes +- Add a task-size routing clause to the managed Guardex AGENTS template. +- Keep small, bounded asks in direct caveman-only mode by default. +- Reserve heavy OMX modes for medium/large scope and allow explicit lightweight escape-hatch prefixes. + +## Impact +- Repos bootstrapped or refreshed by `gx setup` / `gx doctor` get a clearer default routing policy. +- Small asks stay cheaper and simpler. +- Larger, cross-cutting work still has an explicit path into OMX orchestration. diff --git a/openspec/changes/agent-codex-auto-route-small-tasks-to-caveman-and-la-2026-04-22-01-20/specs/guardex-task-size-routing/spec.md b/openspec/changes/agent-codex-auto-route-small-tasks-to-caveman-and-la-2026-04-22-01-20/specs/guardex-task-size-routing/spec.md new file mode 100644 index 0000000..4ead104 --- /dev/null +++ b/openspec/changes/agent-codex-auto-route-small-tasks-to-caveman-and-la-2026-04-22-01-20/specs/guardex-task-size-routing/spec.md @@ -0,0 +1,22 @@ +## ADDED Requirements + +### Requirement: Guardex-managed AGENTS task-size routing +The managed AGENTS block produced by `gx setup` and `gx doctor` SHALL tell downstream repos to keep small, bounded tasks in direct caveman-only mode and reserve heavy OMX orchestration for larger scope. + +#### Scenario: setup refresh writes small-task lightweight routing +- **WHEN** `gx setup` refreshes or installs the managed AGENTS block +- **THEN** the block says small tasks stay in direct caveman-only mode +- **AND** it treats bounded asks such as typos, single-file tweaks, one-liners, and version bumps as lightweight by default. + +#### Scenario: setup refresh writes heavy-mode promotion rules +- **WHEN** the managed AGENTS block is refreshed +- **THEN** it says OMX orchestration is promoted only for medium/large work +- **AND** it names heavy OMX modes as the larger-scope path instead of the default path. + +### Requirement: lightweight escape hatches stay explicit +The managed AGENTS block SHALL document explicit lightweight prefixes that force small-task handling. + +#### Scenario: lightweight prefixes remain available +- **WHEN** the agent reads the managed AGENTS block +- **THEN** it sees `quick:`, `simple:`, `tiny:`, `minor:`, `small:`, `just:`, and `only:` as explicit lightweight escape hatches +- **AND** those prefixes bias the task toward direct caveman-only handling. diff --git a/openspec/changes/agent-codex-auto-route-small-tasks-to-caveman-and-la-2026-04-22-01-20/tasks.md b/openspec/changes/agent-codex-auto-route-small-tasks-to-caveman-and-la-2026-04-22-01-20/tasks.md new file mode 100644 index 0000000..0938c06 --- /dev/null +++ b/openspec/changes/agent-codex-auto-route-small-tasks-to-caveman-and-la-2026-04-22-01-20/tasks.md @@ -0,0 +1,20 @@ +## 1. Spec + +- [x] 1.1 Define Guardex-managed task-size routing requirements for small versus larger tasks. + +## 2. Implementation + +- [x] 2.1 Add the task-size routing clause to `templates/AGENTS.multiagent-safety.md`. +- [x] 2.2 Update install/setup refresh tests so the managed AGENTS block is locked to the new routing policy. + +## 3. Verification + +- [x] 3.1 Run targeted Guardex install tests for managed AGENTS refresh coverage. +- [x] 3.2 Run `openspec validate agent-codex-auto-route-small-tasks-to-caveman-and-la-2026-04-22-01-20 --type change --strict`. + +## 4. Cleanup + +- [ ] 4.1 Commit the Guardex template/test update with Lore trailers. +- [ ] 4.2 Push the agent branch and open/update the PR. +- [ ] 4.3 Merge to `main` and prune the sandbox worktree. +- [ ] 4.4 Record PR URL and final `MERGED` evidence. diff --git a/templates/AGENTS.multiagent-safety.md b/templates/AGENTS.multiagent-safety.md index 9ab89d7..64f93b4 100644 --- a/templates/AGENTS.multiagent-safety.md +++ b/templates/AGENTS.multiagent-safety.md @@ -7,6 +7,9 @@ `GUARDEX_ON=0` disables Guardex for that repo. `GUARDEX_ON=1` explicitly enables Guardex for that repo again. +**Task-size routing.** Small tasks stay in direct caveman-only mode. For typos, single-file tweaks, one-liners, version bumps, or similarly bounded asks, solve directly and do not escalate into heavy OMX orchestration just because a keyword appears. Treat `quick:`, `simple:`, `tiny:`, `minor:`, `small:`, `just:`, and `only:` as explicit lightweight escape hatches. +Promote to OMX orchestration only when the task is medium/large: multi-file behavior changes, API/schema work, refactors, migrations, architecture, cross-cutting scope, or long prompts. Heavy OMX modes (`ralph`, `autopilot`, `team`, `ultrawork`, `swarm`, `ralplan`) are for that larger scope. If the task grows while working, upgrade then. + **Isolation.** Every task runs on a dedicated `agent/*` branch + worktree. Start with `gx branch start "" ""`. Treat the base branch (`main`/`dev`) as read-only while an agent branch is active. Never `git checkout ` on a primary working tree (including nested repos); use `git worktree add` instead. The `.githooks/post-checkout` hook auto-reverts primary-branch switches during agent sessions - bypass only with `GUARDEX_ALLOW_PRIMARY_BRANCH_SWITCH=1`. For every new task, including follow-up work in the same chat/session, if an assigned agent sub-branch/worktree is already open, continue in that sub-branch instead of creating a fresh lane unless the user explicitly redirects scope. Never implement directly on the local/base branch checkout; keep it unchanged and perform all edits in the agent sub-branch/worktree. diff --git a/test/install.test.js b/test/install.test.js index 96734d3..942918a 100644 --- a/test/install.test.js +++ b/test/install.test.js @@ -655,6 +655,8 @@ test('setup refreshes existing managed AGENTS block by default', () => { assert.match(currentAgents, /Guardex is enabled by default/); assert.match(currentAgents, /GUARDEX_ON=0/); assert.match(currentAgents, /GUARDEX_ON=1/); + assert.match(currentAgents, /Small tasks stay in direct caveman-only mode\./); + assert.match(currentAgents, /Promote to OMX orchestration only when the task is medium\/large/); assert.match(currentAgents, /explicit final completion\/cleanup section/); assert.match(currentAgents, /PR URL \+ final `MERGED` evidence/); assert.doesNotMatch(currentAgents, /legacy managed clause/); @@ -688,6 +690,8 @@ Trailing project notes after managed block. assert.match(currentAgents, /Guardex is enabled by default/); assert.match(currentAgents, /GUARDEX_ON=0/); assert.match(currentAgents, /GUARDEX_ON=1/); + assert.match(currentAgents, /Small tasks stay in direct caveman-only mode\./); + assert.match(currentAgents, /Promote to OMX orchestration only when the task is medium\/large/); assert.match(currentAgents, /explicit final completion\/cleanup section/); assert.match(currentAgents, /PR URL \+ final `MERGED` evidence/); assert.doesNotMatch(currentAgents, /legacy managed clause/); @@ -902,6 +906,8 @@ Trailing project notes after managed block. nextAgents, /Never implement directly on the local\/base branch checkout; keep it unchanged and perform all edits in the agent sub-branch\/worktree\./, ); + assert.match(nextAgents, /Small tasks stay in direct caveman-only mode\./); + assert.match(nextAgents, /Promote to OMX orchestration only when the task is medium\/large/); assert.match(nextAgents, /explicit final completion\/cleanup section/); assert.match(nextAgents, /PR URL \+ final `MERGED` evidence/); assert.doesNotMatch(nextAgents, /legacy managed clause/);