Hanson.xyz Dev
5e2bb8585a
- Initialize beads (.beads/ directory) - Add Claude Code hooks for SessionStart/PreCompact - Update CLAUDE.md to clarify all build artifacts are committed - Update .gitignore to allow node_modules and dist
12 KiB
Executable File
12 KiB
Executable File
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 workbd 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 completebd 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.txtDRAFT-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.gitignoreexclusions 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
│ ├── custom-post-types.php
│ ├── 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
│ └── components/
│ ├── agent-card.php
│ ├── agent-card.scss
│ └── ...
├── patterns/
├── front-page.php
├── page.php
├── page-about.php
├── page-contact.php
├── archive.php
├── single.php
├── archive-property.php
├── single-property.php
├── 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 |
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: ACF options page vs Agent CPT?
- Testimonials: Static content vs Testimonial CPT?
- Maps: Embed codes vs Google Maps API?
- Form notifications: Which email address(es)?
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)
- No individual agent pages - all agents on single About page
- Sold properties remain visible (social proof)
- MLS numbers are display-only (no API integration)