Lychee: Instructions file for Codex

Before You Code

• Clarify ambiguity first. Do not plan or implement until every requirement is understood. Ask the user, record unresolved items in the feature's own docs/specs/4-architecture/features/<NNN>-<feature-name>/open-questions.md (create it from docs/specs/templates/feature-open-questions-template.md if missing), and wait for answers. Capture accepted answers by updating the relevant specification’s requirements/NFR/behaviour/telemetry sections so the spec remains the single source of truth for behaviour.
  • No-direct-question rule: For feature work, never ask the user for clarification, approval, or a decision in chat until the matching open question is logged in the feature's open-questions.md (table row + Question Details entry). Treat violations as blockers—stop work, add the missing entry, then resume the conversation by referencing that question ID.
  • Governance/tooling exemption: Questions about work that belongs to no feature (AGENTS.md, runbooks, templates, conventions, scripts, CI) are asked directly in chat without logging. Still present them in the Options A, B, C format below, ordered by preference, and record the outcome in the governing document itself.
  • Whenever you present alternative approaches—whether for open questions or general solution proposals—first capture or update the entry in the feature's open-questions.md (summary row + Question Details section) so the ambiguity lives on disk, then present the stored text to the user inline in chat. Summarise the options directly in your reply (do not tell the user to open the file), call out the question ID (for example, Q-013-01), and follow the numbered-heading/Options A, B, C format with pros/cons. Order the options by preference (Option A is always the recommended path, Option B the next-best, etc.) so the user sees our best advice first. Keep specifications/plans/tasks limited to that ID until the question is resolved.
• Work in small steps. During planning, break every change into logical, self-contained tasks that are expected to complete within ≤90 minutes. Execution can take longer if required; the goal is to plan manageable increments, and prepare a Conventional Commit for each finished slice (see Commit protocol).
• Prime the knowledge map. Skim docs/specs/4-architecture/knowledge-map.md and the up-to-date module snapshot in docs/specs/architecture-graph.json before planning so new work reinforces the architectural relationships already captured there.
• Template usage. Author new specifications, feature plans, task checklists, and open-questions logs using docs/specs/templates/feature-spec-template.md, docs/specs/templates/feature-plan-template.md, docs/specs/templates/feature-tasks-template.md, and docs/specs/templates/feature-open-questions-template.md so structure, metadata, and verification notes stay uniform across features.
• ADR context. Before planning or implementation, skim ADRs under docs/specs/6-decisions/ whose related-features/specs entries reference the active feature ID so high-impact clarifications and architectural decisions are treated as required context alongside the roadmap, spec, plan, tasks, and knowledge map.