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/);