graphone AGENTS.md

Graphone - Agent Quick Reference

Agent Workflow Guidelines

• Check local code first - Before using GitHub tools (read_github, search_github, etc.), always explore the local codebase using standard file tools (read, bash with find/grep, etc.)
• Check pi-mono first for feature implementations - Since graphone is a visual wrapper around pi-mono, look up implementations in local ../pi-mono first (when available). Many features already exist there and can be mimicked or adapted for desktop UI
• Use GitHub tools only when you need to reference external repositories or when explicitly asked about remote code
• Do not track or push docs/ changes - The docs/ folder and all files under it are local-only in this repo context. Do not git add/commit/push anything in docs/ (including with git add -f) unless the user explicitly overrides this rule in the current task.
• Use title + body commit messages by default - Unless the user explicitly requests otherwise, write commits with a concise title and a descriptive body (not title-only).
• Use robust multiline commit messages - Do not embed literal \n in a single git commit -m string. Use multiple -m flags (one per paragraph) or git commit -F with a heredoc/file so line breaks render correctly on GitHub.
• PAT push hygiene - If pushing with GITHUB_PAT, pass it via git auth headers/env only; never echo, print, or otherwise expose the token in commands/output.
• Default autonomous iteration guidance - For general coding-agent-first execution patterns (tests, TDD/debug loops, logs, traces, artifacts, contracts, smokes, escalation), see docs/agent-first-autonomous-iteration-playbook.md
• Visual verification uses readiness loops, not fixed sleeps - Follow the global workflow bash -> readiness loop -> take_screenshot -> bash cleanup. The readiness wait must happen inside the startup bash call because screenshot tools cannot run until that tool call returns.
• Do not start and stop dev helpers in parallel - Startup and cleanup are separate sequential tool calls, with take_screenshot between them. Running start-dev-and-wait.sh and stop-dev.sh in parallel is invalid and defeats the workflow.
• Prefer project helper scripts for visual checks - For Graphone, use tooling/scripts/start-dev-and-wait.sh and tooling/scripts/stop-dev.sh instead of rewriting startup/cleanup loops inline.