Skip to content

AGENTS.md

Latest commit

 

History

History
92 lines (70 loc) · 6.94 KB

AGENTS.md

File metadata and controls

92 lines (70 loc) · 6.94 KB
Raw

AGENTS.md (Local-First)

Keep this file and CLAUDE.md aligned.

This repo is local-first now. Do not reintroduce hosted-service assumptions, remote deployment runbooks, or hardcoded production domains.

Core guardrails

  • Prefer local Mac runtime, local bridge, QR pairing, and daemon workflows.
  • Be an intraprendente agent: proactively inspect local code, protocol/schema, and official sources to confirm facts before replying; do not repeatedly stop to ask for confirmation when the next verification step is safe and obvious.
  • Keep repo isolation by thread/project metadata and local cwd.
  • Do not reintroduce filtering by selected repo in sidebar/content.
  • Keep cross-repo open/create flow with automatic local context switch.
  • Preserve single responsibility: shared logic belongs in services/coordinators, not duplicated in views.
  • Treat this repo as open source: avoid junk code, placeholder hacks, noisy one-off workarounds, and low-signal docs.
  • If you touch docs, keep them local-only and remove stale hosted-service notes instead of adding compatibility layers.
  • Do not create one-off report markdown files in the repo root (security reports, audit notes, scratch summaries, etc.) unless the user explicitly asks for a file. Keep ad-hoc analysis in the chat.
  • For open-source/self-hosted safety, do not log live relay sessionId values or other bearer-like pairing identifiers in server logs; redact or hash them instead.
  • Keep user-facing answers compact by default unless the user explicitly asks for more detail.

iOS runtime + timeline guardrails

  • turn/started may not include a usable turnId: keep the per-thread running fallback.
  • If Stop is tapped and activeTurnIdByThread is missing, resolve via thread/read before interrupting.
  • On reconnect/background recover, rehydrate active turn state so Stop remains visible.
  • Suppress benign background disconnect noise (NWError.posix(.ECONNABORTED)) and retry on foreground.
  • Keep assistant rows item-scoped to avoid timeline flattening/reordering.
  • Merge late reasoning deltas into existing rows; do not spawn fake extra "Thinking..." rows.
  • Ignore late turn-less activity events when the turn is already inactive.
  • Preserve item-aware history reconciliation instead of falling back to turnId-only matching.

Local connection guardrails

  • Prefer saved relay pairing and local connection state as the source of truth.
  • Avoid hardcoded remote domains; default to local values or explicit user config.
  • Keep pairing/auth UX stable: do not clear saved relay info too early during reconnect flows.
  • Preserve reconnect behavior across relaunch when the local host session is still valid.
  • Preserve the QR/local-relay pairing path: do not regress the scanner -> saved pairing -> connect flow by letting onboarding/auto-reconnect race manual scan control.
  • For local relay recovery, keep resumed desktop-thread live mirroring and rollout fallback logic intact so reopened/running threads still recover state even when the rollout file is older than the recent-candidate window.

Build guardrails

  • Do not run Xcode tests unless the user explicitly asks. Do not decide to run them on your own.
  • Markdown files inside Xcode-synced groups can still produce harmless warnings.
  • For small iOS/mobile fixes, prefer inspection and targeted edits over simulator runs by default.

Model selection

Rankings, higher = better. Cost reflects what I actually pay (OpenAI is near-free for me due to a deal), not list price. Intelligence is how hard a problem you can hand the model unsupervised. Taste covers UI/UX, code quality, API design, and copy.

model cost intelligence taste
gpt-5.6-sol 9 8 5
sonnet-5 5 5 7
opus-4.8 4 7 8
fable-5 2 9 9

How to apply:

  • These are defaults, not limits. You have standing permission to override them: if a cheaper model's output doesn't meet the bar, rerun or redo the work with a smarter model without asking. Judge the output, not the price tag. Escalating costs less than shipping mediocre work.
  • Cost is a tie-breaker only; when axes conflict for anything that ships, intelligence > taste > cost.
  • Don't let cost prevent you from using the right model for the job. Instead, take advantage of cheaper options to get more information and try things before moving the work to a more expensive option.
  • Bulk/mechanical work (clear-spec implementation, data analysis, migrations): gpt-5.6-sol — it's effectively free.
  • Anything user-facing (UI, copy, API design) needs taste >= 7.
  • Reviews of plans/implementations: fable-5 or opus-4.8, optionally gpt-5.6-sol as an extra independent perspective.
  • Never use Haiku.
  • Mechanics: gpt-5.6-sol is only reachable through the Codex CLI — codex exec / codex review (my ~/.codex/config.toml defaults to gpt-5.6-sol). Use the codex-implementation, codex-review, and codex-computer-use skills; for work they don't cover (investigation, data analysis), run codex exec -s read-only directly with a self-contained prompt.
  • Claude models (sonnet-5, opus-4.8, fable-5) run via the Agent/Workflow model parameter.

Using gpt-5.5 inside workflows and subagents (the model parameter only takes Claude models, so use a wrapper):

  • Spawn a thin Claude wrapper agent with model: 'sonnet', effort: 'low' whose prompt instructs it to write a self-contained codex prompt, run codex exec via Bash, and return the report (use schema on the wrapper to get structured output back).
  • Always label these agents with a gpt-5.6-sol: prefix, e.g. {label: 'gpt-5.6-sol:review-auth'} — the workflow UI shows the wrapper's Claude model, so the label is the only indication the real worker is gpt-5.6-sol.
  • Codex runs can exceed Bash's 10-minute timeout: pass an explicit timeout, or run in the background and poll for the report file.
  • Parallel gpt-5.6-sol implementation agents must use isolation: 'worktree' so codex edits don't collide in the shared checkout.
  • Workflow token budgets only count Claude tokens; codex work is free and invisible to budget.spent().

Long-running gpt-5.6-sol tasks

gpt-5.6-sol is exceptionally capable on long-running tasks. Give it substantial, multi-step work when it is a good fit; do not artificially split a coherent task merely to make it shorter.

  • The quality of the result depends on the quality of the prompt. Give it a detailed, self-contained brief: the objective, relevant context, constraints, expected outputs, files or systems in scope, acceptance criteria, and the verification required.
  • State important invariants and non-goals explicitly. Do not assume it can infer project-specific constraints that are not in the prompt or the repository instructions.
  • For complex work, ask it to inspect the current state, implement the full solution, run proportionate verification, and report concrete results and remaining risks.
  • Prefer one well-scoped, detailed prompt over a vague prompt followed by many corrective iterations.

Local quick runbook

cd phodex-bridge
npm start