Stop creating AGENTS.md by default

[TraderSamwise]

Summary

• remove Codex's default instructionsFile: "AGENTS.md" so aimux no longer creates repo instruction files by default
• keep Codex startup context on developer_instructions, with file projection only as explicit opt-in config
• clean stale Aimux-managed AGENTS.md blocks from the legacy default path while preserving user-authored files without Aimux markers
• update docs and tests around the new opt-in behavior

Verification

• yarn verify

Summary by CodeRabbit

• Documentation

  • Clarified that repository instruction files are opt-in; the tool does not create them by default and explains how startup instruction injection is configured.

• Bug Fixes

  • Improved cleanup logic to remove stale managed instruction blocks only when appropriate and preserve user-authored content.

• Chores

  • Updated default configuration to align with opt-in instruction file behavior.

• Tests

  • Extended tests to cover opt-in projection and cleanup scenarios.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: de4d44fd-629b-4035-b117-53c631c85874

📥 Commits

Reviewing files that changed from the base of the PR and between 9718c22 and 84ebdd4.

📒 Files selected for processing (1)

• src/multiplexer/runtime-lifecycle-methods.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/multiplexer/runtime-lifecycle-methods.ts

---

📝 Walkthrough

Walkthrough

This PR makes instruction-file projection opt-in (disabled by default), removes codex defaults that auto-create AGENTS.md, updates docs and DEFAULT_CONFIG, adds runtime cleanup to strip or delete legacy Aimux-managed instruction files, and adds tests validating these cleanup scenarios.

Changes

Instruction File Opt-in Configuration and Contract

Layer / File(s)	Summary
Documentation and Config Contract README.md, docs/tool-integration.md, src/config.ts	README and tool-integration docs mark instructionsFile as opt-in and disabled by default; developerInstructionsConfigKey: null disables Codex instruction injection. ToolConfig.instructionsFile JSDoc and DEFAULT_CONFIG for the codex tool remove default instruction-file and developer instructions key settings.

Instruction File Cleanup Implementation

Layer / File(s)	Summary
Legacy File Cleanup and Managed Block Stripping src/multiplexer/runtime-lifecycle-methods.ts	Adds LEGACY_DEFAULT_INSTRUCTION_FILES, cleanupManagedInstructionFile() to strip Aimux-managed blocks or delete empty files, runs cleanup for legacy defaults inside writeInstructionFiles(), and refactors removeInstructionFiles() to use the helper.

Cleanup Behavior Test Coverage

Layer / File(s)	Summary
Test Suite for Instruction File Cleanup src/multiplexer/runtime-lifecycle-methods.test.ts	Adds tests ensuring AGENTS.md is not created when projection is disabled, managed blocks are removed while preserving user content, user-authored files without managed blocks remain unchanged, and generated-only files are deleted when projection is removed. Tests set up .aimux/config.json as needed.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• TraderSamwise/aimux#39: Both PRs change Codex/AGENTS.md "managed instruction block" behavior—related runtime and test updates around merging/cleanup of managed blocks.

Poem

🐰 A rabbit tidies files with care,
No AGENTS.md appearing from thin air.
Managed blocks vanish or gently stay,
User words kept safe along the way.
Tests hop by—everything's fair!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly summarizes the primary change: removing default AGENTS.md creation from Aimux, which is the core objective across all modified files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch phase/no-default-agents-md

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/multiplexer/runtime-lifecycle-methods.ts`:
- Around line 65-75: cleanupManagedInstructionFile performs file I/O and can
throw, but writeInstructionFiles calls it without protection; wrap the call to
cleanupManagedInstructionFile inside writeInstructionFiles in a try/catch
(similar to removeInstructionFiles) and handle failures gracefully (e.g., log
the error via the existing logger or swallow non-fatal errors) so a failed
cleanup during write doesn't crash the runtime.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 65279fc7-4aa5-4d36-998a-fa6cc3380d2f

📥 Commits

Reviewing files that changed from the base of the PR and between 3b47de9 and 9718c22.

📒 Files selected for processing (5)

• README.md
• docs/tool-integration.md
• src/config.ts
• src/multiplexer/runtime-lifecycle-methods.test.ts
• src/multiplexer/runtime-lifecycle-methods.ts