newsjack AGENTS.md

AGENTS.md

Guidance for coding agents working in this repo.

Repo Shape

• apps/cli/ - Go CLI source for newsjack. Commands live in apps/cli/cmd/newsjack/.
• apps/site/ - Next.js site and distribution build. proxy.ts routes curl/wget to install.sh; browser traffic gets the site.
• bin/newsjack - source-checkout shim that runs the Go CLI with go run. Working in this repo, prefer this shim; ~/.newsjack/bin/newsjack is the end-user install path that public skills reference.
• skills/ - public Newsjack skills. These are user-facing runtime instructions.
• fixtures/ - local fixtures and smoke harnesses. Fixture-specific docs, scripts, prompts, and generated run folders belong here.
• eval/ - evaluation artifacts, including reverse-newsjack methodology and dated run results.
• harness/ - local agent/runtime harness support.
• docs/ - planning and architecture notes.

Canonical Boundaries

• Public skill behavior belongs in skills/*/SKILL.md and skill-local support files.
• Fixture usage belongs in the relevant fixtures/*/README.md, scripts, or prompt files, not in public skills.
• skills/newsjack-detector/SKILL.md is the canonical detector pipeline contract.
• fixtures/newsjack-detector-agent/PROMPT.md should only point agents to the canonical detector skill and the fixture profile files. Do not duplicate run commands or profile lists there.
• fixtures/newsjack-detector-agent/README.md owns fixture script usage.

Minimal Memory

Keep Newsjack as stateless as practical. Durable state creates hidden baggage on users' machines, makes behavior harder to reason about, and slows iteration.

• Prefer explicit user-owned files, command inputs, and per-run artifacts over background memory.
• If something can be regenerated with one prompt or one cheap deterministic command, do not save it as durable state.
• If an LLM can derive something from live evidence in one prompt, prefer keeping that derivation in the skill/prompt layer instead of encoding a brittle approximation in Go.
• Persist only state that has a clear product owner and lifecycle: monitor profiles, client briefs, schedules, credentials, run provenance, and recurring-run seen/suppression data.
• Do not persist model-inferred topics, learned assumptions, ranking preferences, or other agent guesses unless the user explicitly promotes them into a profile or brief.
• When state is necessary, make it inspectable, portable, and easy to delete. Avoid adding new local databases, caches, or hidden files unless they are clearly justified.
• One-off commands should be as stateless as possible. Recurring monitors may use limited state for hygiene, but that state should not become the source of truth for discovery or judgment.