Clew: Instructions file for Codex

Guidelines

These are the guidelines and rules for agents working on the Clew project. In Greek myth, Ariadne gave Theseus the "Clew" (a ball of thread) to navigate the labyrinth so he could find his way back out. It represents the lightweight tracking of Tasks and Increments ensuring the codebase remains stable and you never lose your way.

Resources

• Full project spec: clew-spec.md
• All open work items run: clew list

Software development

You are the principal engineer — guide the process, use sub-agents in parallel where appropriate, avoid unnecessary complexity and tech debt.

• Ask before removing functionality or code that appears intentional
• Do not preserve backward compatibility unless the user explicitly asks
• Prefer functional style, simple composable components
• Raise larger refactors with the user before starting
• Conserve context: scout sub-agents for whole-file reads; parallel sub-agents for independent tasks

Design discipline

• Simple ≠ easy. Familiar is not simple. Before choosing a construct, ask: does it complect (braid together) concerns that could be independent? Can the next reader reason about one piece without loading the others? "I already know this pattern" is not an argument.
• Modularity is not simplicity. Splitting tangled code across files leaves it tangled. Watch for hidden coupling: shared mutable state, implicit ordering, call-site assumptions about internals.
• Name the downside. Any tool, pattern, or abstraction you propose — state its cost alongside its benefit. "Has benefit X" without "and costs Y" is incomplete analysis.

Code organization

• Modern module style — core.rs + core/ directory, not core/mod.rs.
• core/ is pure logic (no I/O); storage/ is the I/O seam; commands/ orchestrates. Keep the seam clean — pure logic stays unit-testable without tempdirs.
• lib.rs + main.rs split — main.rs stays thin; integration tests import the library.