Add --agents-file flag to hive-mind spawn command for directive injection

[Copilot]

This PR implements the requested --agents-file <path> flag for the codex-beta hive-mind spawn command, allowing users to automatically inject large directive files (like AGENTS.md) into their prompts without manual copy-pasting.

🎯 Problem Solved

Previously, users had to manually copy and paste the contents of directive files like AGENTS.md into their hive-mind spawn prompts, which was cumbersome and error-prone for large files. This enhancement streamlines the workflow by automating the injection process.

🚀 Implementation Details

Core Functionality

• New CLI option: --agents-file <path> added to hive-mind spawn command
• File injection: Contents are automatically prepended to the user prompt with format: fileContent + "\n\n" + prompt
• Error handling: Graceful fallback to original prompt when files are missing or unreadable
• File validation: Warns users when files exceed 500KB to prevent excessive token usage

User Experience Enhancements

• Success feedback: Gray log message shows the absolute path of injected files (🔗 Injected agents file: <abs path>)
• Warning messages: Yellow warnings for missing files and large files, with clear continuation messages
• Help documentation: New option properly documented in CLI help output
• Backwards compatibility: Zero impact on existing functionality when flag is not used

Example Usage

# Inject AGENTS.md directives into your prompt
codex-beta hive-mind spawn "Create a REST API" --agents-file ./AGENTS.md --agents 7 --algorithm pso

# Graceful handling of missing files
codex-beta hive-mind spawn "Fallback prompt" --agents-file ./MISSING.md
# Output: ⚠️  Warning: Agents file not found: /path/to/MISSING.md
#         Continuing with original prompt...

# Large file warning (>500KB)
codex-beta hive-mind spawn "Task with large context" --agents-file ./large_directives.md
# Output: ⚠️  Warning: Large agents file (600.0KB) may cause high token usage

📚 Documentation & Examples

• README.md: Added new subsection under "Hive-Mind Coordination" with usage examples
• examples/cli-workflows.sh: Added practical example demonstrating the new flag
• .gitignore: Added hive-mind-results.json to prevent tracking generated output files

🧪 Testing

All acceptance criteria have been thoroughly tested:

• ✅ Missing file handling with appropriate warnings
• ✅ Successful file injection with confirmation logging
• ✅ Large file size warnings (>500KB)
• ✅ Backwards compatibility preservation
• ✅ Help output documentation
• ✅ Both manual test commands from requirements work perfectly

🔧 Technical Implementation

The implementation uses Node.js fs and path modules with proper TypeScript error handling. The file reading logic is placed strategically before the existing executeHiveMindSpawn call, with inline comments explaining the injection process. The solution is minimal and focused, changing only what's necessary to implement the feature.

This enhancement significantly improves the developer experience when working with complex agent directives, making the hive-mind spawn command more powerful and user-friendly.

This pull request was created as a result of the following prompt from Copilot chat.

Feature: Add --agents-file flag to hive-mind spawn command

Goal

Enhance the codex-beta hive-mind spawn CLI so users can supply an --agents-file <path> option whose file contents are automatically prepended to (or otherwise combined with) the natural language prompt before spawning the hive-mind. This allows including large directive files (e.g. AGENTS.md) without manually pasting their contents into the prompt each invocation.

Requirements

1. Add a new CLI option --agents-file <path> to the hive-mind spawn command in src/cli/index.ts.
2. When provided and the file exists:
   • Read the file as UTF-8.
   • Prepend its contents plus two newlines to the user prompt (i.e. fullPrompt = fileContent + "\n\n" + prompt).
   • Log a gray informational line noting injection (e.g. 🔗 Injected agents file: <abs path>).
3. If the provided path does not exist:
   • Emit a yellow warning (non-fatal) indicating the file was not found; continue using the original prompt.
4. Pass the resulting fullPrompt (not the original) into executeHiveMindSpawn.
5. Preserve all existing options & logging for the hive-mind spawn path.
6. Do NOT change behavior when --agents-file is omitted (backwards compatible).
7. Update README usage examples to document the new option:
   • Add a short subsection under the Hive-Mind Coordination section demonstrating usage.
   • Include one concise example: codex-beta hive-mind spawn "<prompt>" --agents-file ./AGENTS.md --agents 7 --algorithm pso.
8. Update examples/cli-workflows.sh to add one example line showing hive-mind with --agents-file ./AGENTS.md.
9. Basic validation:
   • If file size > 500KB, log a yellow warning that large context may cause high token usage (still proceed).
10. Keep implementation minimal: no additional config files, no changes to executeHiveMindSpawn signature.
11. Add inline comments describing why injection occurs before calling executeHiveMindSpawn.

Suggested Implementation Notes

• Import fs and path at the top of src/cli/index.ts if not already present in that scope.
• The existing .action(async (prompt, options) => { ... }) for hive-mind spawn should produce let fullPrompt = prompt; then modify as required before final call.
• Use path.resolve(process.cwd(), options.agentsFile) for a stable absolute path log.
• Use synchronous read (fs.readFileSync) since the action is already async and this is a one-time preload; keeps code simpler.
• Use fs.existsSync to test presence; no need for try/catch unless we want to catch read errors (optional: if read throws, warn and fall back to original prompt).

Files to Modify

• src/cli/index.ts
• README.md
• examples/cli-workflows.sh

Acceptance Criteria

• Running codex-beta hive-mind spawn "Test prompt" --agents-file ./AGENTS.md (after build/link) shows the injection log line and produces a hive-mind-results.json as before.
• Running with a non-existent path logs a warning but still runs.
• README documents the new option clearly.
• Example workflow script includes at least one invocation using --agents-file.

Out of Scope

• Automatic default injection (only inject when flag is provided).
• Streaming partial file content.
• Token counting or truncation.

Post-Change Manual Test Commands

pnpm build
npm link
codex-beta hive-mind spawn "Summarize directives and wait for READY." --agents-file ./AGENTS.md --agents 3 --algorithm pso --debug
codex-beta hive-mind spawn "Fallback when file missing" --agents-file ./MISSING_FILE.md

Please implement the changes above and open a pull request.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

Copilot wasn't able to review any files in this pull request.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

Copilot wasn't able to review any files in this pull request.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}