when starting a session, be sure to go through the @requirements.md, @planning.md, and @contributing.md files in this repo to keep our primary goals top of mind. the contributing doc contains development standards, project structure, testing guidelines, and other practices that apply to both human and llm contributors.
at the start of each session, check PLANNING.md to see which phase we're on and what's been completed. also run git status and check recent commits to understand the current project state.
before beginning each new phase, relist the steps in the phase and i'll do a fresh review before you can proceed. while within a phase, feel free to implement what you've got, but stop and ask me if anything becomes unclear. for each item within the phase that has a checkbox, make sure to mark it off and save the planning doc before proceeding to the next one. this helps track progress both within the current session and if we start a new session later.
before starting on implementation within a phase, give me a quick overview of popular libraries and techniques to achieve the task goal. this will help us find a more solid and proven solution out of the gate, rather than "reinvent the wheel" and risk wasted effort.
after a phase is complete, ask me to review and test. once i've had a chance to do so, i'll ask you to do atomic commits for each step in the phase (only combine if it makes sense).
never add claude advertisements to commits (e.g. 🤖 Generated with Claude Code type messages). that's totally tasteless.
once the basic plugin has been created, ln the plugin to the ~/Sites/wordpress-develop/src/wp-content/plugins dir and then use wp-cli to install it from that site (wordpress-develop/src). this is only needed once.
please use commands like git status, ls, or gh to check the existance and changes to files as you work. don't assume and try to modify files without checking first.
when running cli commands, watch for prompts that might require y to continue, etc. don't get stuck waiting for a command that won't return until you've answered those types of questions.
for block implementations, use block.json api v3 and render.php for dynamic blocks (adhering to modern blcok dev practices).
min php requirement is 7.4 for wp at this time, so don't worry about support for older php, and don't set up tests or builds that need to support older php.
don't set up translations in the plugin (e.g. pot files).
remember that as we go along, you should be linting, formatting, and testing when tests are avail. this includes npm or shell scripts that are part of the project.
the planning doc shows implementing tests at a later phase, but i'd prefer adding tests as critical classes or functions are added so that we don't fall behind as things grow more complex. this should help us identify issues with implementation sooner.
the local wp dev site's address is https://wp-src.test and the login creds are admin/password. you should be able to login and validate at least simple stuff directly in the browser, i assume by chrome-devtools mcp (if there's a better way for you to do this, let me know). if there is something that should be tested/checked more than once, we can do an e2e playwright test. let me know when/if you need help with these.
the local dev site's debug log can be found at ../wordpress-development/src/wp-content/debug.log. tail that when making php changes or if something fatals during other testing.
as we go along, if you miss something or make a mistake that we discover during our convo, let's add the appropriate instruction/tip/etc to this file (AGENTS.md) so that it won't happen again. make sure these agent-authored items are added between the hyphen delimiters below so i know which thigns were added by you.
The local dev site admin user has an application password for direct REST API testing:
- Username:
admin - Application Password:
LnUaVWGO3jSpOxDh3RqGW4Yq
This can be used for direct curl testing of REST endpoints, which is more efficient than using Chrome DevTools MCP. Example usage:
# Test search endpoint (get_items)
curl -u admin:LnUaVWGO3jSpOxDh3RqGW4Yq https://wp-src.test/wp-json/setlist-player/v1/youtube/search?q=kyuss
# Test video details endpoint (get_item)
curl -u admin:LnUaVWGO3jSpOxDh3RqGW4Yq https://wp-src.test/wp-json/setlist-player/v1/youtube/video/c_gCpMwqM34Application passwords can be managed via WP-CLI:
# Create new application password
wp user application-password create admin "Application Name"
# List existing application passwords
wp user application-password list admin
# Revoke application password
wp user application-password delete admin <uuid>When registering Gutenberg blocks:
- Always register blocks from the
build/directory, notsrc/ - Use
register_block_type( PLUGIN_DIR . 'build/block.json' ) - In
block.json, reference compiled assets:editorScript:file:./index.jseditorStyle:file:./index.css(NOTeditor.scss)style:file:./style-index.css(NOTstyle.scss)
- The build process copies
block.jsonfromsrc/tobuild/and compiles SCSS to CSS - Pointing to
.scssfiles causes MIME type errors in the browser
When writing commit messages:
- Describe what was implemented/changed, not what was "fixed" or "removed" during the implementation phase. A bug that occurs during implementation is something we'll fix before commit, not something to mention in the commit (don't explain how the sausage was made).
- Focus on the actual changes made (e.g., "Add channel names to playlist items") rather than framing them as corrections unless it's explicitly a bug previously committed that we're addressing.
- Keep messages factual and implementation-focused.
Refine frontend setlist styling and layout
- Convert setlist from grid to compact list view with track numbers
- Add channel names and duration display to setlist items
- Reduce spacing between player and setlist
- Update item hover and active states for cleaner appearance
and if any of this won't work, let me know before you proceed further.