pi-goals: Instructions file for Codex

AGENTS — pi-goals

Project: project-local Pi extension implementing pi-goal.

Primary code: .pi/extensions/goal/. Canonical planning/research:

• .ai/issues/
• .ai/docs/codex-goal-command-research.md
• .ai/.pi-goals/

Extension architecture

Keep the extension modular. Current module map is documented by file names in .pi/extensions/goal/; preserve separation between entrypoint, command/tools, lifecycle/runtime, state/telemetry, prompts, UI/widget, monitor, and shared domain helpers.

Required quality gate

Before substantial implementation:

sentrux gate --save .pi/extensions/goal

After implementation, run the single required gate:

npm run gates:quality

This runs Sentrux gate/check, slop guard, TypeScript validation, and Pi extension load validation.

Rules:

• Run Sentrux against .pi/extensions/goal, not repo root.
• Fix Sentrux degradation/rule failures unless the user explicitly accepts the tradeoff.
• Do not use TypeScript escape-hatch casts in .pi/extensions/goal, especially as unknown as or as any.

Repo artifact hygiene

Do not add repo-tracked docs, validation notes, design notes, or closeout/result files unless they will be read, maintained, or used by future work.

Default ephemeral evidence to /tmp (for example live-probe transcripts, debug logs, one-off summaries, command captures). Keep durable repo artifacts only when:

• the user explicitly asks for a repo-tracked file/path;
• an existing project workflow requires the artifact, such as issue workflow docs under .ai/docs/issue-workflow/...;
• the artifact is a reusable test/probe/script that will be run again; or
• the content is necessary long-term documentation, not just proof that this turn happened.

If the likely future use is "probably never", do not write it into the repo. If a user says to "write results" or "record evidence" without specifying a repo path, prefer /tmp or the final response. Ask before creating a new repo artifact when durability is ambiguous.