[Feature]: Expand AGENTS.md with code conventions and contribution standards

[eddieajau]

Before submitting

• I searched existing issues and did not find a duplicate.
• I am describing a concrete problem or use case, not just a vague idea.

Area

Docs

Problem or use case

AGENTS.md tells agents and contributors what to build and how to verify it, but not how to build it. There are no stated conventions for logging, docblocks, module structure, or test coverage. This means agents generating new code, and humans writing PRs, have to infer conventions from existing code which is inconsistent in places and will diverge further under load.

Proposed solution

Extend AGENTS.md with a Code Conventions section covering:

• Logging: use pino, not custom solutions. Use logger.child() for scoped context.
• Docblocks: all exported functions and types require a JSDoc comment stating intent, parameters, and any non-obvious behaviour or failure modes.
• Module extraction: any logic used in more than one place lives in its own module with a corresponding test file. A module without a test file is incomplete.
• Comments: explain why, not what. Non-obvious invariants, failure modes, and deliberate tradeoffs must be documented inline.
• Module structure: interface, implementation, test. One concern per file. No barrel exports outside packages/shared's explicit subpath pattern.

Why this matters

T3Code uses agents to build itself. An agent reading this codebase to extend it needs the same context a senior engineer would have. Right now that context lives in Julius and Theo's heads. Externalising it into AGENTS.md means every agent and every contributor starts from the same baseline, which directly reduces review overhead and PR noise.

Smallest useful scope

A single new ## Code Conventions section in AGENTS.md. No code changes required.

After that, select a file or collection, devise a maintenance prompt against the new conventions, and iterate until the desired result is one-shotable. The conventions document becomes the spec; the prompt becomes the test.

Alternatives considered

A separate CONTRIBUTING.md section. Rejected because AGENTS.md is already the document agents are directed to. Splitting guidance across two documents creates drift.

Risks or tradeoffs

Conventions ossify patterns. If the codebase needs to evolve away from a stated convention, AGENTS.md needs updating or agents will fight the change. Low risk at this stage; high value as the contributor surface grows.

Examples or references

The existing Maintainability section in AGENTS.md is the right pattern. This extends that instinct with enough specificity to act on.

Contribution

• I would be open to helping implement this.