claude-fleet-monitor: Instructions file for Codex

Agent Contributing Guide

Guidelines for AI agents (Claude Code, Copilot, etc.) contributing to this repository.

Agent SDLC

Use docs/SDLC.md for substantial initiatives and explicit workflow requests. Astra leads architecture/orchestration; Sol at high handles senior work and independent review; Luna at xhigh handles bounded work under Sol review. Use actual runtime models, isolated worktrees and autonomous signed-off local commits within approved scope. Follow the CTO-approved issue-level feature-branch PR gates in the profile; Astra owns child merges, and final main merge remains the CTO gate. The profile records the adoption authorization, workflow baseline, checks and instruction reconciliation. Preserve unrelated rules below.

Before You Start

1. Read CLAUDE.md for architecture and design decisions.
2. Run pytest to confirm the test suite passes before making changes.
3. Check existing issues and PRs to avoid duplicate work.

Making Changes

• Write tests for new functionality. Tests live in tests/ and use pytest with tmp_path fixtures.
• Keep changes cross-platform. Never assume Linux (/proc, pgrep). Use sys.platform checks and the abstractions in discovery.py.
• Shared process discovery and session filesystem access go through discovery.py. The hook owns fleet event writes, CLI install/uninstall owns harness configuration, and terminal APIs own terminal integration. Do not duplicate platform-specific discovery logic in consumers.
• The hook (hook.py) must stay fast. No heavy imports at module level, no network calls.

Terminal APIs

• Focus logic goes through focus.py, which delegates to terminal APIs in terminal_apis/.
• Each terminal emulator has its own module implementing TerminalAPI (see terminal_apis/base.py).
• To add a new terminal: create terminal_apis/newterminal.py, implement the ABC, add to TERMINALS list in terminal_apis/__init__.py, add detection env var to TERMINAL_PROCESS_NAMES in tmux.py for nested terminal support.
• Terminal detection happens at hook time via env vars, not at focus time. Each session stores its terminal and terminal_env in the fleet JSON.
• For multiplexers (tmux, zellij) that run inside other terminals, raise_window() must detect the parent terminal via process tree walking and chain to its API.