Repository navigation

TOOLS.md — Tool & Command Conventions

Available Tools

The agent operates through Codex (VSCode extension or CLI), which provides:

File read/write — read, create, edit, delete files
Shell commands — run terminal commands (with approval gates)
Git operations — status, diff, add, commit, branch, log
Search — find files, grep content, navigate repo structure

Command Conventions

Always use relative paths from the repo root when referencing files.
Quote paths containing spaces.
Prefer non-destructive commands; use --dry-run flags when available for previews.
Capture command output in logs when it's relevant to the task.

Approval-Gated Operations

The following commands require explicit user approval before execution:

Git (Destructive / External)

git push (any remote)
git reset --hard
git rebase (interactive or non-interactive)
git branch -D (force delete)
git checkout . or git restore . (discard all changes)
Any force flag (--force, -f) on git operations

Filesystem (Destructive)

rm -rf or rm on multiple files
mv affecting many files or directories
Any operation on files outside the project root

System / Network

Package installs (npm install, pip install, apt install, etc.)
Network requests (curl, wget, API calls)
Process management (kill, service restarts)
Anything touching environment variables or secrets

Logging Format

When logging tool usage to daily logs, use this format:

- [HH:MM] TOOL: <command or action>
  Result: <brief outcome>
  Files: <affected files, if any>

Error Handling

If a command fails, log the error and assess before retrying.
Maximum 2 retries for the same command.
If still failing after retries, stop and ask the user for guidance.
Never suppress or ignore errors silently.