brianhansonxyz/homeproz
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Streamline CLAUDE.md

Browse Source 
Remove completed decisions, outdated planning details, and verbose
documentation. Keep only essential rules and reference info.

Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Hanson.xyz Dev
2025-12-01 01:29:44 -06:00
parent d1185184bf
commit ec5a309555
1 changed files with 35 additions and 459 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+35 -459
View File
@@ -1,480 +1,56 @@
# HomeProz WordPress Theme
## TOOLING: BEADS (Issue Tracking)
Custom WordPress theme for HomeProz Real Estate (Albert Lea, MN). Dark/rust brand aesthetic with ACF-powered property listings.
Git-backed issue tracker for AI agents. Use `bd` for task management, NOT markdown TODOs or TodoWrite.
## Development Rules
**Git policy**: `.beads/` directory IS committed. `issues.jsonl` is the source of truth (db rebuilds from it). Issue state travels with code.
1. **No emojis** - nowhere in code, commits, docs, or conversation
2. **Tailwind CSS + SCSS** - compiled via Vite
3. **jQuery** - for all JS functionality
4. **Co-locate files** - SCSS/JS live alongside PHP templates
5. **Page-scoped styles** - wrap in `.Page_Class_Name { }`, early return in JS
6. **Server-side render** - no client-side templating
7. **No custom animations** - keep it static and fast
8. **ASK before architectural decisions**
**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 <id>` | View issue details |
| `bd update <id> --status in_progress` | Claim/start work |
| `bd close <id>` | Complete issue |
| `bd sync` | Sync with git remote |
| `bd list --status open` | List open issues |
| `bd dep add <id> <blocks-id>` | Add dependency |
### Workflow
1. `bd ready` ^f^r find available work
2. `bd update <id> --status in_progress` ^f^r claim it
3. Work on the issue
4. Discover new work? ^f^r `bd create "title" --deps discovered-from:<parent-id>`
5. `bd close <id>` ^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 `<body>` tag:
```php
<body class="Home_Page">
<body class="Properties_Archive">
<body class="Single_Property">
<body class="About_Page">
<body class="Contact_Page">
<body class="Blog_Archive">
<body class="Single_Post">
```
### 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:
## Build
```bash
# Theme management
wp theme list
wp theme activate homeproz
# Plugin management
wp plugin install <plugin-name> --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 <command>
cd wp-content/themes/homeproz
npm run build
```
**Note:** Always use `--allow-root` flag when running as root user.
## Tools
### dev_commit.sh
- **WP-CLI**: `wp --allow-root <command>`
- **Dev commits**: `./dev_commit.sh "message"` (includes DB snapshot)
A helper script for development checkpoints. Located at `/var/www/html/dev_commit.sh`.
## Theme Options
```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)?
---
Access via `homeproz_get_option('key')`:
- `phone`, `email`, `address`, `facebook`, `tiktok`
## Custom Post Types
### Property CPT (`property`)
### Property (`/properties/`)
- ACF: price, address, beds/baths/sqft, gallery, documents, listing_agent
- Taxonomies: `property_status` (Active/Pending/Sold), `property_type`, `property_location`
- Location dropdown only shows communities with active/pending properties
**URL Structure:** `/properties/` (archive), `/properties/{slug}/` (single)
### Agent (`/agents/`)
- ACF: phone, email, bio, gallery, social links, order, disabled toggle
- Disabled agents: 404 on profile, office contact on property cards
**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)
## Key Helpers
**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');
// Get locations with active/pending properties only
$locations = homeproz_get_active_locations();
// Contact page with property inquiry prefill
$url = add_query_arg('property', urlencode($title), home_url('/contact/'));
```
---
## Page Classes
## 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
`Home_Page`, `Properties_Archive`, `Single_Property`, `About_Page`, `Contact_Page`, `Blog_Archive`, `Single_Post`, `Agents_Archive`, `Single_Agent`, `Search_Page`, `Error_404`