## TOOLING: BEADS (Issue Tracking) Git-backed issue tracker for AI agents. Use `bd` for task management, NOT markdown TODOs or TodoWrite. **Git policy**: `.beads/` directory IS committed. `issues.jsonl` is the source of truth (db rebuilds from it). Issue state travels with code. **Hooks installed**: SessionStart and PreCompact hooks auto-run `bd prime` to inject workflow context. ### Essential Commands | Command | Purpose | |---------|---------| | `bd ready` | Show unblocked issues ready to work | | `bd create "title"` | Create new issue | | `bd show ` | View issue details | | `bd update --status in_progress` | Claim/start work | | `bd close ` | Complete issue | | `bd sync` | Sync with git remote | | `bd list --status open` | List open issues | | `bd dep add

` | Add dependency | ### Workflow 1. `bd ready` ^f^r find available work 2. `bd update --status in_progress` ^f^r claim it 3. Work on the issue 4. Discover new work? ^f^r `bd create "title" --deps discovered-from:` 5. `bd close ` ^f^r mark complete 6. `bd sync` ^f^r push changes ### Issue Types & Priorities **Types**: `bug`, `feature`, `task`, `epic`, `chore` **Priorities**: `0` (critical) ^f^r `4` (backlog), default `2` **End of session**: Create issues for discovered work, `bd sync`, verify clean git state. # PROJECT: HomeProz WordPress Website Development ## Project Overview **Client:** HomeProz Real Estate (Albert Lea, MN area) **Developer:** Hanson.xyz **Contract:** $6,000 development + $600/yr hosting **Goal:** Build a custom WordPress theme with ACF-powered property listing system, replacing their current GoDaddy Website Builder site while maintaining their dark/rust brand aesthetic. ## Reference Documents All planning documents located in: `/var/www/html/contract/Contracts/WordPress-Website/_scratch/site_analysis/` | Document | Purpose | |----------|---------| | `DESIGN-DOCUMENT.md` | Visual design specs, colors, typography, layouts, all template specifications | | `IMPLEMENTATION-PLAN.md` | Technical architecture, ACF fields, CPT structure, phase breakdown | | `homepage-full.png` | Screenshot of existing site (full page) | | `homepage-viewport.png` | Screenshot of existing site (above fold) | Contract documents in parent directory: - `CONTRACT-AT-A-GLANCE.txt` - `DRAFT-HomeProz-WordPress-Website-Contract.txt` --- ## Development Mandates ### Communication & Output 1. **No emojis** - Never use emojis in code, website output, commit messages, documentation, or conversation. This is a professional project. ### UI & Styling 1. **Use Tailwind CSS** as the UI framework 2. **Use SCSS** for custom styles, compiled via Vite 3. **Page-scoped SCSS**: Every page-specific SCSS file must be wrapped: ```scss .The_Page_Name { // all rules for this page go here } ``` 4. **Page body classes**: Every page template must add a class to the `` tag: ```php ``` ### JavaScript 1. **Use jQuery** for all JS functionality 2. **Page-scoped JS**: All page-specific JS must start with early return: ```javascript (function($) { if (!$('.The_Page_Name').length) return; // page-specific code here })(jQuery); ``` 3. **No inline scripts** - all JS in external files 4. **No inline event handlers** - use jQuery event binding 5. **Use Vite** to bundle JS/CSS ### File Organization 1. **Co-locate related files** - JS and SCSS files live alongside their related PHP templates, NOT in separate `/js/` or `/css/` directories 2. Example structure: ``` template-parts/ ├── property/ │ ├── property-card.php │ ├── property-card.scss │ └── property-card.js ├── components/ │ ├── hero-section.php │ ├── hero-section.scss ``` ### Error Handling 1. **No empty catch blocks** - never write `try {} catch() { /* error occurred */ }` 2. **Let errors surface** - only use try/catch when genuinely required for functionality 3. **No fallback/legacy implementations** - assume modern browser, assume libraries exist 4. Dual implementations create security holes and maintenance nightmares ### Rendering 1. **Server-side render everything** - no client-side template rendering 2. **No preloaders/spinners** except: - AJAX lookups (property filtering, search) - Only show spinner on FIRST data load - Subsequent AJAX calls show stale data until new data arrives 3. **Exception**: Search page will be AJAX-based and refined iteratively ### Animations 1. **No custom animations** - no hover effects, no transitions, no "slide up on scroll" 2. **Exception**: Animations built into Tailwind/UI library are acceptable 3. Keep it static and fast ### Version Control 1. **Git is for SNAPSHOTS** - not optimized for public/collaboration 2. **Commit everything** - build artifacts (`dist/`, `node_modules/`), database dumps, and all generated files are committed. No `.gitignore` exclusions for build output. 3. After every development phase: ```bash mysqldump -u [user] -p [database] > db-snapshot-phase-X.sql git add -A git commit -m "Phase X: [description]" ``` 4. Database dumps committed alongside code ### Decision Making 1. **ASK before implementing** when facing architectural choices 2. Examples of decisions requiring developer input: - CSS framework choice - Preprocessor choice - JS library choice - Plugin alternatives - Data structure approaches 3. Get clarity, then proceed --- ## Technology Stack | Component | Choice | |-----------|--------| | CMS | WordPress 6.x | | PHP | 8.1+ | | Database | MySQL/MariaDB | | CSS Framework | Tailwind CSS | | CSS Preprocessor | SCSS | | JavaScript | jQuery | | Build Tool | Vite | | Custom Fields | ACF Pro | | Forms | Contact Form 7 | | SEO | Yoast SEO | ## Tools Available ### WP-CLI WP-CLI is installed at `/usr/local/bin/wp`. Use it for WordPress administration tasks: ```bash # Theme management wp theme list wp theme activate homeproz # Plugin management wp plugin install --activate wp plugin list # Database operations wp db export backup.sql wp db import backup.sql # Cache and transients wp cache flush wp transient delete --all # User management wp user list wp user create username email@example.com --role=administrator # Options wp option get siteurl wp option update blogname "HomeProz Real Estate" # Rewrite rules wp rewrite flush # Run with --allow-root since we're running as root # All commands should use: wp --allow-root ``` **Note:** Always use `--allow-root` flag when running as root user. ### dev_commit.sh A helper script for development checkpoints. Located at `/var/www/html/dev_commit.sh`. ```bash # Usage ./dev_commit.sh "Step X.X: Description of what was done" # What it does: # 1. Dumps database to db-snapshots/db-snapshot.sql (overwrites each time) # 2. Runs git add -A # 3. Commits with your message ``` **MANDATE:** Use `./dev_commit.sh` after completing each step in the implementation plan. This ensures we have a database snapshot with every code commit. Example: ```bash ./dev_commit.sh "Step 1.3: Configure theme.json with brand colors" ``` --- ## Theme Structure ``` themes/homeproz/ ├── assets/ │ └── images/ ├── src/ # Vite source files │ ├── main.js # JS entry point │ ├── main.scss # SCSS entry point │ └── tailwind.css # Tailwind imports ├── dist/ # Vite build output ├── inc/ │ ├── acf-fields.php # All ACF field definitions │ ├── custom-post-types.php # Property & Agent CPTs │ ├── enqueue.php │ ├── theme-setup.php │ └── template-functions.php ├── template-parts/ │ ├── header/ │ │ ├── site-header.php │ │ ├── site-header.scss │ │ └── navigation.js │ ├── footer/ │ │ └── site-footer.php │ ├── property/ │ │ ├── property-card.php │ │ ├── property-card.scss │ │ ├── property-filters.php │ │ ├── property-filters.js │ │ ├── property-filters.scss │ │ ├── property-gallery.php │ │ ├── property-gallery.js │ │ ├── property-gallery.scss │ │ ├── property-agent.php # Agent card for property sidebar │ │ └── single-property.scss │ ├── agent/ │ │ ├── single-agent.scss │ │ └── archive-agent.scss │ └── components/ │ ├── hero-section.php │ ├── hero-section.scss │ ├── cta-section.php │ ├── cta-section.scss │ └── ... ├── patterns/ ├── front-page.php ├── page.php ├── page-about.php ├── page-contact.php # Supports ?property= prefill ├── archive.php ├── single.php ├── archive-property.php ├── single-property.php ├── archive-agent.php # Agent listing page ├── single-agent.php # Agent profile page ├── search.php ├── 404.php ├── header.php ├── footer.php ├── functions.php ├── style.css ├── theme.json ├── package.json ├── vite.config.js ├── tailwind.config.js └── postcss.config.js ``` --- ## Brand Specifications ### Colors | Name | Hex | Usage | |------|-----|-------| | Background Dark | `#0A0A0A` | Primary background | | Background Card | `#161616` | Elevated surfaces | | Accent Primary | `#9F3730` | CTAs, buttons | | Accent Hover | `#C8473F` | Button hover | | Accent Light | `#BF524B` | Links | | Text Primary | `#F5F5F5` | Headlines | | Text Muted | `#B0B0B0` | Body text | | Border | `#2A2A2A` | Dividers | | Success | `#2E7D32` | Active listings | | Warning | `#F9A825` | Pending listings | | Sold | `#757575` | Sold listings | ### Typography | Element | Font | |---------|------| | Headlines | Abril Fatface | | Body | Inter (or Droid Sans) | --- ## Page Class Names Reference | Template | Body Class | |----------|------------| | `front-page.php` | `Home_Page` | | `page.php` | `Default_Page` | | `page-about.php` | `About_Page` | | `page-contact.php` | `Contact_Page` | | `archive.php` | `Blog_Archive` | | `single.php` | `Single_Post` | | `archive-property.php` | `Properties_Archive` | | `single-property.php` | `Single_Property` | | `archive-agent.php` | `Agents_Archive` | | `single-agent.php` | `Single_Agent` | | `search.php` | `Search_Page` | | `404.php` | `Error_404` | --- ## Development Phases 1. **Foundation** - Theme scaffold, Vite setup, Tailwind config, header/footer 2. **Property System** - CPT, ACF fields, archive, single, filters 3. **Page Templates** - Homepage, About, Contact, Blog, 404, Search 4. **Block Patterns** - Reusable Gutenberg patterns 5. **Content & SEO** - Schema markup, meta tags, initial content 6. **Performance & Security** - Caching, optimization, security hardening 7. **Testing & Training** - QA, documentation, client training Each phase ends with: ```bash mysqldump homeproz > db-snapshot-phase-X.sql git add -A git commit -m "Phase X complete: [description]" ``` --- ## Open Decisions (Resolve Before Starting) 1. ~~CSS Framework~~ → **Tailwind CSS** (confirmed) 2. ~~JS Library~~ → **jQuery** (confirmed) 3. ~~Preprocessor~~ → **SCSS** (confirmed) 4. ~~Build tool~~ → **Vite** (confirmed) 5. ~~Agents~~ → **Agent CPT** (implemented) 6. Testimonials: Static content vs Testimonial CPT? 7. Maps: Embed codes vs Google Maps API? 8. Form notifications: Which email address(es)? --- ## Custom Post Types ### Property CPT (`property`) **URL Structure:** `/properties/` (archive), `/properties/{slug}/` (single) **ACF Fields:** - **Basic Info:** `property_price`, `street_address`, `city`, `state`, `zip_code`, `mls_number` - **Details:** `bedrooms`, `bathrooms`, `square_feet`, `lot_size`, `year_built`, `garage` - **Content:** `short_description`, `property_features` (checkbox), `property_gallery` (gallery) - **Documents:** `property_documents` (repeater with file + label) - **External:** `external_listing_url` (URL to Zillow/MLS listing) - **Agent:** `listing_agent` (post_object → Agent CPT) **Taxonomies:** - `property_status`: Active, Pending, Sold, Coming Soon - `property_type`: Single Family, Townhouse, Condo, Land, Commercial, Multi-Family ### Agent CPT (`agent`) **URL Structure:** `/agents/` (archive), `/agents/{slug}/` (single) **ACF Fields:** - **Contact:** `agent_phone`, `agent_email`, `agent_website`, `agent_title`, `agent_license` - **Bio:** `agent_short_bio` (textarea, max 300 chars) - **Gallery:** `agent_gallery` (gallery for additional photos; featured image is primary headshot) - **Social:** `agent_social_links` (repeater: platform select + URL) - **Settings:** `agent_order` (number, default 10), `agent_disabled` (toggle) **Disabled Agent Behavior:** - Does not appear on `/agents/` listing - Profile page returns 404 - On property listings: shows name/photo but uses office phone, no profile link, "Contact Us" button instead of email --- ## Theme Options (ACF Options Page) Located at **Appearance → Theme Options** | Field | Key | Usage | |-------|-----|-------| | Phone | `theme_phone` | Office phone number (used via `homeproz_get_option('phone')`) | | Email | `theme_email` | Office email | | Address | `theme_address` | Office address | | Facebook | `theme_facebook` | Facebook page URL | | TikTok | `theme_tiktok` | TikTok profile URL | Access in templates: ```php $phone = homeproz_get_option('phone'); $email = homeproz_get_option('email'); ``` --- ## Contact Page Property Inquiry The contact page supports pre-filling the message textarea with a property inquiry. **URL Format:** `/contact/?property=Property+Name+Here` **Behavior:** - Extracts `property` GET parameter - Pre-fills message with: "I would like to get more information on property: {Property Name}" - Works with fallback form and Contact Form 7 (via JavaScript) **Usage in templates:** ```php $contact_url = add_query_arg('property', urlencode($property_title), home_url('/contact/')); ``` --- ## Notes - Dark theme is unconventional for real estate but matches client brand - Property images use 16:10 aspect ratio (better for real estate than 16:9) - Agent listing page shows agents ordered by `agent_order` field, then alphabetically - Sold properties remain visible (social proof) - MLS numbers are display-only (no API integration) - Properties imported from homeprozrealestate.com with external listing URLs to Zillow