Files

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

15 KiB

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

bd ready ^f^r find available work
bd update <id> --status in_progress ^f^r claim it
Work on the issue
Discover new work? ^f^r bd create "title" --deps discovered-from:<parent-id>
bd close <id> ^f^r mark complete
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

No emojis - Never use emojis in code, website output, commit messages, documentation, or conversation. This is a professional project.

UI & Styling

Use Tailwind CSS as the UI framework
Use SCSS for custom styles, compiled via Vite
Page-scoped SCSS: Every page-specific SCSS file must be wrapped:
```
.The_Page_Name {
  // all rules for this page go here
}
```

Page body classes: Every page template must add a class to the <body> tag:

<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

Use jQuery for all JS functionality

Page-scoped JS: All page-specific JS must start with early return:

(function($) {
  if (!$('.The_Page_Name').length) return;

  // page-specific code here
})(jQuery);

No inline scripts - all JS in external files
No inline event handlers - use jQuery event binding
Use Vite to bundle JS/CSS

File Organization

Co-locate related files - JS and SCSS files live alongside their related PHP templates, NOT in separate /js/ or /css/ directories

Example structure:

template-parts/
├── property/
│   ├── property-card.php
│   ├── property-card.scss
│   └── property-card.js
├── components/
│   ├── hero-section.php
│   ├── hero-section.scss

Error Handling

No empty catch blocks - never write try {} catch() { /* error occurred */ }
Let errors surface - only use try/catch when genuinely required for functionality
No fallback/legacy implementations - assume modern browser, assume libraries exist
Dual implementations create security holes and maintenance nightmares

Rendering

Server-side render everything - no client-side template rendering
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
Exception: Search page will be AJAX-based and refined iteratively

Animations

No custom animations - no hover effects, no transitions, no "slide up on scroll"
Exception: Animations built into Tailwind/UI library are acceptable
Keep it static and fast

Version Control

Git is for SNAPSHOTS - not optimized for public/collaboration
Commit everything - build artifacts (dist/, node_modules/), database dumps, and all generated files are committed. No .gitignore exclusions for build output.

After every development phase:

mysqldump -u [user] -p [database] > db-snapshot-phase-X.sql
git add -A
git commit -m "Phase X: [description]"

Database dumps committed alongside code

Decision Making

ASK before implementing when facing architectural choices
Examples of decisions requiring developer input:
- CSS framework choice
- Preprocessor choice
- JS library choice
- Plugin alternatives
- Data structure approaches
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:

# 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.

# 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:

./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

Foundation - Theme scaffold, Vite setup, Tailwind config, header/footer
Property System - CPT, ACF fields, archive, single, filters
Page Templates - Homepage, About, Contact, Blog, 404, Search
Block Patterns - Reusable Gutenberg patterns
Content & SEO - Schema markup, meta tags, initial content
Performance & Security - Caching, optimization, security hardening
Testing & Training - QA, documentation, client training

Each phase ends with:

mysqldump homeproz > db-snapshot-phase-X.sql
git add -A
git commit -m "Phase X complete: [description]"

Open Decisions (Resolve Before Starting)

~~CSS Framework~~ → Tailwind CSS (confirmed)
~~JS Library~~ → jQuery (confirmed)
~~Preprocessor~~ → SCSS (confirmed)
~~Build tool~~ → Vite (confirmed)
~~Agents~~ → Agent CPT (implemented)
Testimonials: Static content vs Testimonial CPT?
Maps: Embed codes vs Google Maps API?
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)