From 7bc3094d49f34a10a545daa6b48c72765e0a1d92 Mon Sep 17 00:00:00 2001 From: NagyVikt Date: Wed, 22 Apr 2026 23:37:41 +0200 Subject: [PATCH] Give managed repos the same low-overhead AGENTS contract Guardex setup only installed the safety block, so downstream repos missed the token-budget and Caveman execution rules we already rely on in recodee. This extends the managed template with repo-generic guidance, syncs the checked-in AGENTS block, and locks the new wording with setup/prompt tests. Constraint: Must stay repo-generic so fresh repos do not depend on recodee-only files or skills Rejected: Copy recodee AGENTS wholesale | would reintroduce repo-specific paths and bloat the managed prompt surface Confidence: high Scope-risk: narrow Reversibility: clean Directive: Keep future token-budget or Caveman prompt rules in the managed template and checked-in block together Tested: node --test test/setup.test.js test/prompt.test.js Tested: openspec validate agent-codex-mirror-recodee-token-and-caveman-agents-2026-04-22-23-28 --type change --strict Tested: openspec validate --specs Not-tested: gx branch finish --via-pr --wait-for-merge --cleanup --- AGENTS.md | 23 +++++++++++ .../.openspec.yaml | 2 + .../proposal.md | 23 +++++++++++ .../managed-repo-agents-contract/spec.md | 25 +++++++++++ .../tasks.md | 41 +++++++++++++++++++ templates/AGENTS.multiagent-safety.md | 23 +++++++++++ test/prompt.test.js | 11 +++++ test/setup.test.js | 6 +++ 8 files changed, 154 insertions(+) create mode 100644 openspec/changes/agent-codex-mirror-recodee-token-and-caveman-agents-2026-04-22-23-28/.openspec.yaml create mode 100644 openspec/changes/agent-codex-mirror-recodee-token-and-caveman-agents-2026-04-22-23-28/proposal.md create mode 100644 openspec/changes/agent-codex-mirror-recodee-token-and-caveman-agents-2026-04-22-23-28/specs/managed-repo-agents-contract/spec.md create mode 100644 openspec/changes/agent-codex-mirror-recodee-token-and-caveman-agents-2026-04-22-23-28/tasks.md diff --git a/AGENTS.md b/AGENTS.md index c23b2f30..757e9e61 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -321,6 +321,29 @@ scripts/openspec/init-plan-workspace.sh **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 "" ""`. 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/openspec/changes/agent-codex-mirror-recodee-token-and-caveman-agents-2026-04-22-23-28/.openspec.yaml b/openspec/changes/agent-codex-mirror-recodee-token-and-caveman-agents-2026-04-22-23-28/.openspec.yaml new file mode 100644 index 00000000..25345f42 --- /dev/null +++ b/openspec/changes/agent-codex-mirror-recodee-token-and-caveman-agents-2026-04-22-23-28/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-04-22 diff --git a/openspec/changes/agent-codex-mirror-recodee-token-and-caveman-agents-2026-04-22-23-28/proposal.md b/openspec/changes/agent-codex-mirror-recodee-token-and-caveman-agents-2026-04-22-23-28/proposal.md new file mode 100644 index 00000000..8f22fad2 --- /dev/null +++ b/openspec/changes/agent-codex-mirror-recodee-token-and-caveman-agents-2026-04-22-23-28/proposal.md @@ -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. diff --git a/openspec/changes/agent-codex-mirror-recodee-token-and-caveman-agents-2026-04-22-23-28/specs/managed-repo-agents-contract/spec.md b/openspec/changes/agent-codex-mirror-recodee-token-and-caveman-agents-2026-04-22-23-28/specs/managed-repo-agents-contract/spec.md new file mode 100644 index 00000000..87083cb1 --- /dev/null +++ b/openspec/changes/agent-codex-mirror-recodee-token-and-caveman-agents-2026-04-22-23-28/specs/managed-repo-agents-contract/spec.md @@ -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. diff --git a/openspec/changes/agent-codex-mirror-recodee-token-and-caveman-agents-2026-04-22-23-28/tasks.md b/openspec/changes/agent-codex-mirror-recodee-token-and-caveman-agents-2026-04-22-23-28/tasks.md new file mode 100644 index 00000000..6b0775fc --- /dev/null +++ b/openspec/changes/agent-codex-mirror-recodee-token-and-caveman-agents-2026-04-22-23-28/tasks.md @@ -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 "//,//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). diff --git a/templates/AGENTS.multiagent-safety.md b/templates/AGENTS.multiagent-safety.md index 55b2112a..cb13f7ac 100644 --- a/templates/AGENTS.multiagent-safety.md +++ b/templates/AGENTS.multiagent-safety.md @@ -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 "" ""`. 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/prompt.test.js b/test/prompt.test.js index 7d983da0..93d9ec67 100644 --- a/test/prompt.test.js +++ b/test/prompt.test.js @@ -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, //); + 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(); diff --git a/test/setup.test.js b/test/setup.test.js index c81c780f..bf951564 100644 --- a/test/setup.test.js +++ b/test/setup.test.js @@ -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/); });