brianhansonxyz/homeproz
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ff25ffcceb256bfae1822f7c19eba43d18635508
homeproz/CLAUDE.md
T
Hanson.xyz Dev c2c2703568 Update CLAUDE.md with CPT, ACF, and feature documentation 
- Added Agent CPT to theme structure and page class reference
- Documented Property CPT with all ACF fields and taxonomies
- Documented Agent CPT with ACF fields and disabled behavior
- Added Theme Options (ACF Options Page) documentation
- Documented contact page property inquiry feature
- Updated open decisions (Agents decision resolved)
- Updated notes section

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

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-30 19:11:57 -06:00

481 lines
15 KiB
Markdown
Executable File
Raw Blame History

## 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 <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:
```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>
```
**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
Reference in New Issue View Git Blame Copy Permalink