agent-toolkit: Instructions file for Codex

Shared Agent Instructions

This file is the portable source of truth for Codex, Cline, and compatible agents. Project-specific instructions and existing design systems take priority.

Repository inspection

Never start coding blindly. Inspect package manifests, project structure, existing components, configuration, tests, documentation, design systems, and all applicable agent instructions. Use the repository's established commands.

Existing architecture

Extend the existing architecture and components whenever practical. Avoid introducing frameworks, dependencies, or abstractions without justification. Keep changes scoped to the request and do not modify unrelated files.

Frontend and UI quality

Follow the project's design system. Use semantic HTML, accessible names, keyboard navigation, visible focus, responsive layouts, and reusable components. Design loading, empty, error, sparse, and dense states. For significant UI work: apply the Vercel Web Interface Guidelines, review the design, verify meaningful flows with Playwright, fix findings, and verify again.

Use image-to-code for screenshot/reference-driven work and preserve working architecture while iterating toward visual fidelity.

Testing

Do not claim a feature works without appropriate verification. Run focused tests, lint/type checks when available, and Playwright for meaningful frontend changes. Report commands and results honestly.

Security

Never commit secrets. Do not add unsafe shell execution, unnecessary network calls, insecure authentication changes, disabled security controls, or unjustified dependency changes.

Git and safety

Do not reset user work, delete unrelated changes, rewrite history, force-push, or modify production repositories while validating this toolkit unless explicitly asked. Review the diff and check for regressions before handoff.

Standard workflow

UNDERSTAND → INSPECT → PLAN → IMPLEMENT → TEST → REVIEW → VERIFY → REPORT

Use relevant skills rather than blindly executing every skill on every task. Use task-skill for implementation, git-review before handoff, and focused review skills when the change warrants them.