Merge pull request #120 from brainstormforce/claude-docs-setup

Author: kiransbsf

.claude/settings.json

@@ -0,0 +1,28 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx grunt:*)",
+      "Bash(npm install)",
+      "Bash(composer install)",
+      "Bash(./vendor/bin/phpcs:*)",
+      "Bash(git status)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git branch:*)",
+      "Bash(git checkout:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git push:*)",
+      "Bash(git remote:*)",
+      "Bash(ls:*)",
+      "Bash(find:*)",
+      "Bash(cat:*)",
+      "Bash(wc:*)"
+    ],
+    "deny": [
+      "Bash(rm -rf:*)",
+      "Bash(git push --force:*)",
+      "Bash(git reset --hard:*)"
+    ]
+  }
+}

.distignore

@@ -32,3 +32,7 @@ node_modules
 package-lock.json
 .github
 .wordpress-org
+
+.claude
+CLAUDE.md
+internal-docs

.gitignore

@@ -1,6 +1,9 @@
-.DS_Store
-Thumbs.db
-wp-cli.local.yml
-node_modules/
-*.zip
-*.tar.gz
+.DS_Store
+Thumbs.db
+wp-cli.local.yml
+node_modules/
+*.zip
+*.tar.gz
+
+.claude/settings.local.json
+config.bat

CLAUDE.md

@@ -0,0 +1,55 @@
+# Fullwidth Page Templates
+
+## Project Overview
+
+Fullwidth Page Templates is a WordPress plugin by Brainstorm Force. Create full-width landing pages with any theme using page builder templates.
+
+- **Version:** 1.2.0
+- **Text Domain:** fullwidth-templates
+- **Main File:** fullwidth-page-template.php
+- **Requires:** WordPress, PHP 5.6+
+
+## Tech Stack
+
+- **Language:** PHP
+- **Platform:** WordPress
+- **Build:** Grunt (i18n, readme conversion)
+- **Coding Standards:** PHPCS with WordPress standards
+
+## Commands
+
+```bash
+# Install dependencies
+npm install
+composer install
+
+# Build (i18n + readme)
+npx grunt
+
+# Generate translations
+npx grunt i18n
+
+# Convert readme.txt to README.md
+npx grunt readme
+
+# Run PHPCS
+./vendor/bin/phpcs .
+```
+
+## Architecture
+
+This is a WordPress plugin following standard WordPress patterns:
+- Entry point: `fullwidth-page-template.php`
+- Constants defined for version, file path, base, dir, and URI
+- Classes loaded via `after_setup_theme` or `plugins_loaded` hook
+- Follows WordPress Coding Standards (WPCS)
+
+## Conventions
+
+- Use WordPress hooks (`add_action`, `add_filter`) for extensibility
+- Prefix all functions and classes to avoid conflicts
+- Use `fullwidth-templates` text domain for all translatable strings
+- Escape all output (`esc_html`, `esc_attr`, `esc_url`, `wp_kses`)
+- Sanitize all input (`sanitize_text_field`, `absint`, etc.)
+- Use nonces for form submissions and AJAX requests
+- Follow WordPress PHP coding standards

Gruntfile.js

@@ -0,0 +1,25 @@
+# Fullwidth Page Templates — Internal Documentation
+
+> Auto-generated documentation for developer onboarding and AI agent understanding.
+
+## Quick Facts
+
+| Key | Value |
+|-----|-------|
+| **Plugin Name** | Fullwidth Page Templates |
+| **Version** | 1.2.0 |
+| **Text Domain** | fullwidth-templates |
+| **Main File** | `fullwidth-page-template.php` |
+| **PHP Files** | 13 |
+| **Build Tool** | Grunt |
+| **Stack** | WordPress Plugin (PHP) |
+
+## Description
+
+Create full-width landing pages with any theme using page builder templates.
+
+## Index
+
+- [Architecture](architecture.md) — High-level architecture and data flow
+- [Codebase Map](codebase-map.md) — Directory structure and key files
+- [AI Agent Guide](ai-agent-guide.md) — Key patterns and locations for AI-assisted development

internal-docs/README.md

@@ -0,0 +1,40 @@
+# AI Agent Guide — Fullwidth Page Templates
+
+## Quick Start for AI Agents
+
+1. **Entry point:** Start at `fullwidth-page-template.php` to understand plugin initialization
+2. **Constants:** Look for `define()` calls in the main file for paths and versions
+3. **Hook registration:** Search for `add_action` and `add_filter` to find where functionality is attached
+4. **Text domain:** Use `fullwidth-templates` for all translatable strings
+
+## Common Tasks
+
+### Adding a new feature
+1. Create a new class file in the appropriate directory
+2. Register it via `require_once` in the loader or main class
+3. Use `add_action`/`add_filter` to hook into WordPress
+4. Follow existing class patterns for consistency
+
+### Modifying existing behavior
+1. Find the relevant class by searching for the hook or function name
+2. Check for filters that allow modification without editing core files
+3. If editing, maintain the existing code style and patterns
+
+### Adding translatable strings
+1. Wrap strings in `__( 'text', 'fullwidth-templates' )` or `esc_html__( 'text', 'fullwidth-templates' )`
+2. Run `npx grunt i18n` to update the POT file
+
+## WordPress Checklist
+
+- [ ] All output is escaped (`esc_html`, `esc_attr`, `esc_url`, `wp_kses`)
+- [ ] All input is sanitized (`sanitize_text_field`, `absint`, etc.)
+- [ ] Nonces used for forms and AJAX (`wp_nonce_field`, `check_ajax_referer`)
+- [ ] Capability checks before privileged operations (`current_user_can`)
+- [ ] Text domain `fullwidth-templates` used for all user-facing strings
+- [ ] No direct file access (files start with `defined( 'ABSPATH' )` check or silence)
+
+## Pitfalls
+
+- Plugin may depend on Astra theme being active — check for theme dependency logic
+- Constants are defined only once — don't redefine them
+- Follow WordPress coding standards (spaces not tabs for alignment, tabs for indentation)

internal-docs/ai-agent-guide.md

@@ -0,0 +1,32 @@
+# Architecture — Fullwidth Page Templates
+
+## Overview
+
+Fullwidth Page Templates is a WordPress plugin that follows standard WordPress plugin architecture patterns.
+
+## Entry Point
+
+The plugin entry point is `fullwidth-page-template.php`, which:
+1. Defines plugin constants (version, file path, base name, directory, URI)
+2. Loads the main plugin class via a WordPress hook (`after_setup_theme` or `plugins_loaded`)
+
+## Request Lifecycle
+
+1. WordPress loads the plugin via `fullwidth-page-template.php`
+2. Constants are defined for use throughout the plugin
+3. Main class is instantiated/loaded on the appropriate hook
+4. Classes register their own hooks and filters
+5. Frontend/admin output is rendered when WordPress fires the relevant hooks
+
+## Key Patterns
+
+- **Hook-based architecture:** All functionality is attached via `add_action()` and `add_filter()`
+- **Class autoloading:** Classes are loaded via `require_once` in the main plugin file or loader class
+- **Separation of concerns:** Admin and frontend code are separated into different classes/directories
+- **WordPress Customizer integration:** Settings are registered via the Customizer API where applicable
+
+## Dependencies
+
+- WordPress core (required)
+- Astra theme (recommended/required for full functionality)
+- No external PHP dependencies beyond WordPress

internal-docs/architecture.md

@@ -0,0 +1,24 @@
+# Codebase Map — Fullwidth Page Templates
+
+## Directory Structure
+
+```
+fullwidth-templates/
+├── fullwidth-page-template.php                    # Plugin entry point
+├── admin/bsf-analytics/class-bsf-analytics-loader.php
+├── admin/bsf-analytics/class-bsf-analytics-stats.php
+├── admin/bsf-analytics/class-bsf-analytics.php
+├── admin/notices/class-astra-notices.php
+├── class-fullwidth-page-templates.php
+├── fullwidth-page-template.php
+├── templates/default/template-helpers.php
+├── templates/default/template-page-builder-no-header-footer.php
+├── templates/default/template-page-builder-no-sidebar.php
+├── templates/default/template-page-builder.php
+├── .distignore                            # WordPress.org distribution exclusions
+├── .gitignore                             # Git exclusions
+├── Gruntfile.js                           # Grunt build configuration
+├── package.json                           # Node.js dependencies
+├── CLAUDE.md                              # Claude Code project context
+└── .claude/settings.json                  # Claude Code tool permissions
+```