cokaremote/AGENTS.md

Agent Execution Policy

Coka MCP long-running work

Use the managed-task tools for builds, tests, package installs, Docker builds, integration tests, migrations, benchmarks, and any command that may take more than a few seconds or emit substantial output.

• Prefer start_managed_task over exec_command for long-running work.
• Give every managed task a stable, descriptive taskKey such as root-ci, backend-tests, or docker-build-api.
• Reuse the same taskKey when recovering after a ChatGPT/message-stream interruption. Do not start the same command again merely because the response stream was interrupted.
• Before retrying work after an interruption, call list_managed_tasks or read_managed_task and inspect the existing task state.
• Use read_managed_task with long waits rather than repeatedly polling at short intervals.
• Managed-task responses are intentionally compact. Full stdout/stderr is stored in the task log file; inspect only the reported tail/highlights unless deeper diagnostics are required.
• Do not dump full build/test logs into MCP responses. Prefer exit status, important lines, and a bounded tail.
• Group related repository inspection and edits into coherent calls instead of issuing many tiny shell commands.
• Run targeted tests before the full suite. Run the full CI/build once near the end unless a failure requires another run.
• Never re-run an already successful build/test solely to reconstruct conversational context.

Low-level process tools

Use exec_command, read_process, write_stdin, and terminate_process when interactive stdin, exact paged stdout/stderr, or low-level process control is specifically required. They remain the escape hatch, not the default for long-running non-interactive work.

Recovery order

When a response is interrupted:

1. Inspect list_managed_tasks.
2. Reuse the matching task by taskKey.
3. If it is still running, wait with read_managed_task.
4. If it finished, consume its existing result and log summary.
5. Re-run only when the prior task failed for a reason that requires a retry, or when an explicit fresh run is requested.