A developer guide to using the IM Base AI.md as project instructions for AI-assisted development.

Overview

AI.md is IM Base’s current guide for AI-assisted development. It defines the architectural and implementation rules that AI tools must follow; it is not the general user-facing theme guide.

It complements README.md and the documents under docs/. README.md provides the human user and developer overview, while the other documentation records development information and focused rules. AI.md does not replace inspecting the current source, related files, references, hooks, selectors, generated assets, and documentation before making changes.

• README.md explains the theme to human users and developers.
• AI.md defines architecture and implementation rules for AI-assisted development.
• docs/current-status.md records the current implementation state, TODOs, and development history.

Why AI.md Exists

IM Base is a reusable WordPress starter theme for agencies and freelance developers, so its core must remain suitable for different client projects. It provides common infrastructure without imposing a finished design or project-specific content. AI.md makes this boundary explicit: project-specific requirements and design decisions must not be added to the theme core without an explicit request.

AI-assisted changes can otherwise introduce guessed behavior, duplicate WordPress functionality, move responsibilities outside the established structure, or alter naming, breakpoints, saved data, and other compatibility rules. AI.md directs assistants to inspect the current implementation first, follow the existing architecture, make the smallest requested change, and avoid unrelated files or worktree changes.

What AI.md Defines

AI.md defines IM Base as a lightweight WordPress starter theme whose core must remain reusable across client projects. Project-specific content and design must not be added without an explicit requirement. The guide favors WordPress Core and native PHP, CSS, and JavaScript, restrained and accessible responsive design, predictable responsibilities, maintainability, backward compatibility, and no unnecessary external libraries. WordPress setup, feature modules, templates, assets, documentation, settings, and translations must remain in their established directories; functions.php is limited to module loading, and new architectural layers or moved files require prior review.

SCSS changes begin in the source files and are synchronized to generated CSS. Layout files handle page and region behavior, while parts contain shared, single-responsibility components registered through the parts index. JavaScript uses native APIs, reads responsive values from window.imbResponsiveSettings, stays consistent with CSS ranges, resets state when modes change, and preserves accessibility behavior and existing imb- selectors and data attributes. Navigation uses registered WordPress menus and the IM Base Walker, without fallback menus, generated page lists, or navigation HTML in core/setup.php; childless items are links, parent items are buttons, and submenu behavior and animation differ between mobile and larger screens. WordPress APIs, the existing imb_theme_settings structure, translation functions, and stored-data contracts must be preserved. IM Base identifiers use imb_ in PHP and imb- in CSS and data attributes, while the theme name and text domain remain im-base.

For AI-assisted work, inspect related implementation, hooks, selectors, generated assets, and documentation before editing. Do not invent requirements or behavior, duplicate WordPress features, alter architecture, naming, breakpoints, saved-data keys, or unrelated files without authorization, or edit generated CSS without the corresponding SCSS change. Documentation-only requests must not modify implementation, and documentation must not claim completion without verification or mix completed work with future TODOs. Define requirements and non-goals, make the smallest suitable change, run applicable syntax, compilation, browser, accessibility, responsive, and git diff –check reviews, report results and remaining risks, and commit only when explicitly requested.

• Prefer WordPress Core APIs and native PHP, CSS, and JavaScript.
• Edit SCSS first and synchronize generated CSS.
• Read responsive breakpoints from window.imbResponsiveSettings instead of hardcoding them.
• Use WordPress standard navigation menus and the IM Base Walker; do not create fallback menus or navigation HTML in core/setup.php.
• Use imb_ for IM Base PHP identifiers and imb- for CSS classes and data attributes.
• Inspect current code before editing, make the smallest requested change, verify it, and commit only when explicitly requested.

Using AI.md with Coding Assistants

When using Codex, Claude Code, or another coding assistant with IM Base, explicitly ask it to read AI.md before making changes; do not assume the file will be loaded automatically. State the requirement and explicit non-goals, then ask the assistant to inspect the target implementation and related files, references, hooks, selectors, generated assets, and documentation before editing.

Request the smallest change that satisfies the requirement and exclude unrelated files. Run applicable syntax checks, compilation, focused browser checks, and git diff –check, then review the changed files, behavior, verification results, and remaining risks yourself. Ask for a commit only after review and only when a commit is explicitly required.

Before making changes, read AI.md and follow the project rules.
Investigate the current implementation first.
Do not change unrelated files.
Do not commit.

• State the requirement and explicit non-goals.
• Ask the assistant to read AI.md before making changes.
• Inspect related files, hooks, selectors, generated assets, and documentation.
• Implement the smallest change that satisfies the requirement.
• Run applicable lint, tests, compilation, browser checks, and git diff –check.
• Review the result before requesting a commit.

AI.md and Other Documentation

README.md provides the current user and developer overview of the theme. AI.md defines the architectural and implementation rules for AI-assisted development, including project structure, coding conventions, and development workflow. It complements README.md and the documentation under docs/; it does not replace inspection of the current source code.

docs/current-status.md records the current implementation state, pending work, cautions, and development history. Focused documents such as docs/prefix-naming-rule.md provide detailed rules for a specific concern, such as identifier prefixes. When changing documentation, check related Markdown files for contradictions and keep the documented rules, implementation status, and focused guidance consistent.

• README.md: user and developer overview of the current theme.
• AI.md: mandatory architectural and implementation rules for AI-assisted work.
• docs/current-status.md: current implementation state, pending work, cautions, and development history.
• Focused docs: detailed rules for a specific concern, such as prefix naming.

Keeping AI.md Current

Update AI.md when an architectural decision becomes a formal project rule. This includes changes to directory responsibilities or module loading, SCSS and generated CSS, JavaScript and responsive behavior, navigation contracts, WordPress APIs or stored data, naming conventions, and the development workflow.

Clarify AI.md when recurring assistant mistakes show that an existing rule is ambiguous or incomplete. Before finalizing changes, verify them against the implementation and related documentation so the source code and project guidance remain consistent and do not describe unverified behavior as a rule.

• A new architectural decision becomes a formal project rule.
• Directory responsibilities or the module-loading structure changes.
• SCSS, generated CSS, JavaScript, responsive, or navigation contracts change.
• WordPress API, naming, compatibility, or stored-data rules change.
• AI assistants repeatedly make the same incorrect implementation assumption.