AGENTS.md

Guidance for coding agents working on Thinklogi, a mobile-first A/B decision feed with a Codex-operated product harness.

Project Overview

Thinklogi is a static web app plus harness loop. The product loop is simple: users post dilemmas with two choices, feed visitors vote by pressing and holding a choice, results appear immediately, and optional reason chips replace long comment threads. The first harness goal is whether a dilemma can reach 30 votes within 24 hours.

Main areas:

• public/: static app runtime and harness snapshot.
• src/: source logic used by the build.
• harness/: Codex-operated harness state, goals, evidence, agents, and CLI.
• tests/: Node test runner coverage.
• .thinklogi/harness-state.json: local harness state, mirrored into public/harnessSnapshot.json.

Setup Commands

bashnpm run harness:init
npm run harness:tick
npm run harness:status
npm run dev
npm test
npm run build

Use npm run harness:run only when the task explicitly needs multiple harness cycles.

Product Rules

• Keep voting intentionally low-friction: the press-and-hold interaction is the core mechanic.
• Reason chips should stay lightweight and structured; avoid reopening a generic comments product.
• Mobile-first scanning matters more than dense desktop chrome.
• The Agent screen should reflect harness state from public/harnessSnapshot.json, not invented live status.

Harness Rules

• Treat harness/cli.mjs as the entry point.
• Keep goal state and evidence files structured and inspectable.
• If changing harness behavior, update both the state transition logic and the public snapshot mirror.
• Avoid background automation assumptions unless the current task provides the runner.

Code Style

• Preserve the static-app constraint.
• Keep decision logic testable outside the browser.
• Avoid adding app-wide frameworks for a narrow feed behavior.
• Keep generated dist/ output separate from source edits unless the task explicitly asks for build output.

Testing

Use:

bashnpm test
npm run build

For vote behavior, test timing, cancellation, result calculation, and reason-chip handling. For harness behavior, test state initialization, tick transitions, evidence collection, and public snapshot output.

Security And Privacy

• Do not put private user data into harness snapshots.
• Keep local harness state repo-relative in docs.
• Do not publish machine-specific paths or local server URLs.

Commit And PR Rules

• Explain whether the change affects product UI, decision logic, harness operations, or build output.
• Include the exact harness command used when reporting harness changes.
• Do not claim a goal metric moved unless it is present in harness evidence.