recodeee · NagyVikt · Apr 22, 2026 · Apr 22, 2026
@@ -321,6 +321,29 @@ scripts/openspec/init-plan-workspace.sh <plan-slug>
 **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.
 
+## Token / Context Budget
+
+Default: less word, same proof.
+
+- For prompts about `token inefficiency`, `reviewer mode`, `minimal token overhead`, or session waste patterns, switch into low-overhead mode: plan in at most 4 bullets, execute by phase, batch related reads/commands, avoid duplicate reads and interactive loops, keep outputs compact, and verify once per phase.
+- Low output alone is not a defect. A bounded run that finishes in roughly <=10 steps is usually fine; low output spread across 20+ steps with rising per-turn input is fragmentation and should be treated as context growth first.
+- Startup / resume summaries stay tiny: `branch`, `task`, `blocker`, `next step`, and `evidence`.
+- Memory-driven starts stay ordered: read active `.omx/state` first, then one live `.omx/notepad.md` handoff, then external memory only when the task depends on prior repo decisions, a previous lane, or ambiguous continuity. Stop after the first 1-2 relevant hits.
+- Front-load scaffold/path discovery into one grouped inspection pass. Avoid serial `ls` / `find` / `rg` / `cat` retries that only rediscover the same path state.
+- Treat repeated `write_stdin`, repeated `sed` / `cat` peeks, and tiny diagnostic follow-up checks as strong negative signals. If they appear alongside climbing input cost, stop the probe loop and batch the next phase.
+- Tool / hook summaries stay tiny: command, status, last meaningful lines only. Drop routine hook boilerplate.
+- Treat local edit/commit, remote publish/PR, CI diagnosis, and cleanup as bounded phases. Do not spend fresh narration or approval turns on obvious safe follow-ons inside an already authorized phase unless the risk changes.
+- When a session turns fragmented, collapse back to inspect once, patch once, verify once, and summarize once.
+- Keep `.omx/notepad.md` lean: live handoffs only. Use exactly `branch`, `task`, `blocker`, `next step`, and `evidence`; move narrative proof into OpenSpec artifacts, PRs, or command output.
+
+## OMX Caveman Style
+
+- Commentary and progress updates use smart-caveman `ultra` by default: drop articles, filler, pleasantries, and hedging. Fragments are fine when they stay clear.
+- Answer order stays fixed: answer first, cause next, fix or next step last. If yes/no fits, say yes/no first.
+- Keep literals exact: code, commands, file paths, flags, env vars, URLs, numbers, timestamps, and error text are never caveman-compressed.
+- Auto-clarity wins: switch back to `lite` or normal wording for security warnings, irreversible actions, privacy/compliance notes, ordered instructions where fragments may confuse, or when the user is confused and needs more detail.
+- Boundaries stay normal/exact for code, commits, PR text, specs, logs, and blocker evidence.
+
 **Isolation.** Every task runs on a dedicated `agent/*` branch + worktree. Start with `gx branch start "<task>" "<agent-name>"`. Treat the base branch (`main`/`dev`) as read-only while an agent branch is active. Never `git checkout <branch>` 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.

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-22
@@ -0,0 +1,23 @@
+## Why
+
+- Guardex-managed repos already get the safety/worktree contract, but they do not
+  inherit the tighter token-budget and Caveman execution rules that live in
+  `recodee`'s repo contract.
+- Users setting up new repos with `gx setup` should get the same low-overhead
+  AGENTS guidance by default instead of re-adding it repo by repo.
+
+## What Changes
+
+- Extend the managed `AGENTS.md` snippet with compact `Token / Context Budget`
+  and `OMX Caveman Style` sections that are generic enough for any Guardex
+  repo.
+- Sync this repo's checked-in `AGENTS.md` managed block to the updated template.
+- Lock the new wording with focused install/setup and `gx prompt --snippet`
+  regressions.
+
+## Impact
+
+- Affected surfaces: `templates/AGENTS.multiagent-safety.md`, the checked-in
+  `AGENTS.md` managed block, and prompt/setup regression coverage.
+- Risk is low because the change is prompt/contract-only, but template drift
+  would immediately affect newly bootstrapped repos if left untested.
@@ -0,0 +1,25 @@
+## ADDED Requirements
+
+### Requirement: Managed repos inherit low-overhead execution guidance
+The Guardex-managed `AGENTS.md` block SHALL include repo-generic token/context
+budget guidance so freshly bootstrapped repos inherit the same low-overhead
+execution rules used in `recodee`.
+
+#### Scenario: Setup installs token budget guidance
+- **GIVEN** `gx setup` or `gx install` creates or refreshes `AGENTS.md`
+- **WHEN** the managed block is written into a repo
+- **THEN** it includes a `## Token / Context Budget` section
+- **AND** that section tells agents to keep startup summaries tiny, batch work
+  by phase, and collapse fragmented runs back to inspect once / patch once /
+  verify once.
+
+### Requirement: Managed repos inherit Caveman output rules
+The Guardex-managed `AGENTS.md` block SHALL include repo-generic Caveman output
+rules so downstream repos match the same commentary and literal-preservation
+behavior used in `recodee`.
+
+#### Scenario: Prompt snippet exposes Caveman rules
+- **WHEN** a user runs `gx prompt --snippet`
+- **THEN** the printed managed block includes `## OMX Caveman Style`
+- **AND** it preserves the answer-first / cause-next / next-step-last ordering
+  plus the rule that literals stay exact.
@@ -0,0 +1,41 @@
+## Definition of Done
+
+This change is complete only when **all** of the following are true:
+
+- Every checkbox below is checked.
+- The agent branch reaches `MERGED` state on `origin` and the PR URL + state are recorded in the completion handoff.
+- If any step blocks (test failure, conflict, ambiguous result), append a `BLOCKED:` line under section 4 explaining the blocker and **STOP**. Do not tick remaining cleanup boxes; do not silently skip the cleanup pipeline.
+
+## Handoff
+
+- Handoff: change=`agent-codex-mirror-recodee-token-and-caveman-agents-2026-04-22-23-28`; branch=`agent/codex/mirror-recodee-token-and-caveman-agents-2026-04-22-23-28`; scope=`templates/AGENTS.multiagent-safety.md, checked-in AGENTS.md, focused AGENTS prompt/setup regressions`; action=`mirror recodee-style token/caveman rules into the managed template and finish the sandbox`.
+- Copy prompt: Continue `agent-codex-mirror-recodee-token-and-caveman-agents-2026-04-22-23-28` on branch `agent/codex/mirror-recodee-token-and-caveman-agents-2026-04-22-23-28`. Work inside the existing sandbox, review `openspec/changes/agent-codex-mirror-recodee-token-and-caveman-agents-2026-04-22-23-28/tasks.md`, continue from the current state instead of creating a new sandbox, and when the work is done run `gx branch finish --branch agent/codex/mirror-recodee-token-and-caveman-agents-2026-04-22-23-28 --base main --via-pr --wait-for-merge --cleanup`.
+
+## 1. Specification
+
+- [x] 1.1 Finalize proposal scope and acceptance criteria for `agent-codex-mirror-recodee-token-and-caveman-agents-2026-04-22-23-28`.
+- [x] 1.2 Define normative requirements in `specs/managed-repo-agents-contract/spec.md`.
+
+## 2. Implementation
+
+- [x] 2.1 Extend the managed AGENTS template and checked-in managed block with repo-generic `Token / Context Budget` and `OMX Caveman Style` sections.
+- [x] 2.2 Add/update focused regression coverage for setup/install output and `gx prompt --snippet`.
+
+## 3. Verification
+
+- [x] 3.1 Run `node --test test/setup.test.js test/prompt.test.js`.
+- [x] 3.2 Run `openspec validate agent-codex-mirror-recodee-token-and-caveman-agents-2026-04-22-23-28 --type change --strict`.
+- [x] 3.3 Run `openspec validate --specs`.
+
+Verification evidence:
+- `node --test test/setup.test.js test/prompt.test.js` (pass, 51/51 setup tests + 9/9 prompt tests)
+- `openspec validate agent-codex-mirror-recodee-token-and-caveman-agents-2026-04-22-23-28 --type change --strict` (pass)
+- `openspec validate --specs` (`No items found to validate.`)
+- `diff -u <(sed -n "/<!-- multiagent-safety:START -->/,/<!-- multiagent-safety:END -->/p" AGENTS.md) templates/AGENTS.multiagent-safety.md` (clean; no output)
+- `git -C /home/deadpool/Documents/recodee/gitguardex status --short` (clean primary checkout)
+
+## 4. Cleanup (mandatory; run before claiming completion)
+
+- [ ] 4.1 Run the cleanup pipeline: `gx branch finish --branch agent/codex/mirror-recodee-token-and-caveman-agents-2026-04-22-23-28 --base main --via-pr --wait-for-merge --cleanup`. This handles commit -> push -> PR create -> merge wait -> worktree prune in one invocation.
+- [ ] 4.2 Record the PR URL and final merge state (`MERGED`) in the completion handoff.
+- [ ] 4.3 Confirm the sandbox worktree is gone (`git worktree list` no longer shows the agent path; `git branch -a` shows no surviving local/remote refs for the branch).
@@ -10,6 +10,29 @@
 **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.
 
+## Token / Context Budget
+
+Default: less word, same proof.
+
+- For prompts about `token inefficiency`, `reviewer mode`, `minimal token overhead`, or session waste patterns, switch into low-overhead mode: plan in at most 4 bullets, execute by phase, batch related reads/commands, avoid duplicate reads and interactive loops, keep outputs compact, and verify once per phase.
+- Low output alone is not a defect. A bounded run that finishes in roughly <=10 steps is usually fine; low output spread across 20+ steps with rising per-turn input is fragmentation and should be treated as context growth first.
+- Startup / resume summaries stay tiny: `branch`, `task`, `blocker`, `next step`, and `evidence`.
+- Memory-driven starts stay ordered: read active `.omx/state` first, then one live `.omx/notepad.md` handoff, then external memory only when the task depends on prior repo decisions, a previous lane, or ambiguous continuity. Stop after the first 1-2 relevant hits.
+- Front-load scaffold/path discovery into one grouped inspection pass. Avoid serial `ls` / `find` / `rg` / `cat` retries that only rediscover the same path state.
+- Treat repeated `write_stdin`, repeated `sed` / `cat` peeks, and tiny diagnostic follow-up checks as strong negative signals. If they appear alongside climbing input cost, stop the probe loop and batch the next phase.
+- Tool / hook summaries stay tiny: command, status, last meaningful lines only. Drop routine hook boilerplate.
+- Treat local edit/commit, remote publish/PR, CI diagnosis, and cleanup as bounded phases. Do not spend fresh narration or approval turns on obvious safe follow-ons inside an already authorized phase unless the risk changes.
+- When a session turns fragmented, collapse back to inspect once, patch once, verify once, and summarize once.
+- Keep `.omx/notepad.md` lean: live handoffs only. Use exactly `branch`, `task`, `blocker`, `next step`, and `evidence`; move narrative proof into OpenSpec artifacts, PRs, or command output.
+
+## OMX Caveman Style
+
+- Commentary and progress updates use smart-caveman `ultra` by default: drop articles, filler, pleasantries, and hedging. Fragments are fine when they stay clear.
+- Answer order stays fixed: answer first, cause next, fix or next step last. If yes/no fits, say yes/no first.
+- Keep literals exact: code, commands, file paths, flags, env vars, URLs, numbers, timestamps, and error text are never caveman-compressed.
+- Auto-clarity wins: switch back to `lite` or normal wording for security warnings, irreversible actions, privacy/compliance notes, ordered instructions where fragments may confuse, or when the user is confused and needs more detail.
+- Boundaries stay normal/exact for code, commits, PR text, specs, logs, and blocker evidence.
+
 **Isolation.** Every task runs on a dedicated `agent/*` branch + worktree. Start with `gx branch start "<task>" "<agent-name>"`. Treat the base branch (`main`/`dev`) as read-only while an agent branch is active. Never `git checkout <branch>` 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.

@@ -141,6 +141,17 @@ test('prompt --exec rejects prompt-only parts', () => {
   assert.match(result.stderr, /Exec-capable parts:/);
 });
 
+test('prompt --snippet prints the managed AGENTS template with token budget and caveman rules', () => {
+  const repoDir = initRepo();
+  const result = runNode(['prompt', '--snippet'], repoDir);
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+  assert.match(result.stdout, /<!-- multiagent-safety:START -->/);
+  assert.match(result.stdout, /## Token \/ Context Budget/);
+  assert.match(result.stdout, /Default: less word, same proof\./);
+  assert.match(result.stdout, /## OMX Caveman Style/);
+  assert.match(result.stdout, /Answer order stays fixed: answer first, cause next, fix or next step last\./);
+});
+
 
 test('deprecated copy-prompt alias still works and warns', () => {
   const repoDir = initRepo();

@@ -142,6 +142,10 @@ test('setup provisions workflow files and repo config', () => {
     agentsContent,
     /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/,
   );
+  assert.match(agentsContent, /## Token \/ Context Budget/);
+  assert.match(agentsContent, /Default: less word, same proof\./);
+  assert.match(agentsContent, /## OMX Caveman Style/);
+  assert.match(agentsContent, /Answer order stays fixed: answer first, cause next, fix or next step last\./);
 
   const gitignoreContent = fs.readFileSync(path.join(repoDir, '.gitignore'), 'utf8');
   assert.match(gitignoreContent, /# multiagent-safety:START/);
@@ -821,6 +825,8 @@ test('install configures AGENTS managed policy block with GX contract wording',
     agentsContent,
     /OMX completion policy: when a task is done, the agent must commit the task changes, push the agent branch, and create\/update a PR/,
   );
+  assert.match(agentsContent, /## Token \/ Context Budget/);
+  assert.match(agentsContent, /## OMX Caveman Style/);
 });