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

chore: add Claude Code scaffolding and internal docs

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

@@ -33,4 +33,5 @@ borders-for-default-menu.json
 defaults.json
 no-toggle-border-fix.json
 cghooks.lock
-wp-cli.local.yml
+wp-cli.local.yml
+.claude/settings.local.json

CLAUDE.md

@@ -0,0 +1,55 @@
+# Sidebar Manager
+
+## Project Overview
+
+Sidebar Manager is a WordPress plugin by Brainstorm Force. Create and manage custom sidebars with target rules.
+
+- **Version:** 2.0.0
+- **Text Domain:** bsfsidebars
+- **Main File:** sidebar-manager.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: `sidebar-manager.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 `bsfsidebars` 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

@@ -136,6 +136,9 @@ module.exports = function( grunt ) {
                     '!admin/bsf-analytics/package.json',
                     '!admin/bsf-analytics/package-lock.json',
                     '!admin/bsf-analytics/phpcs.xml.dist',
+					'!CLAUDE.md',
+					'!.claude/**',
+					'!internal-docs/**',
 				],
 				dest: 'sidebar-manager/'
 			}

internal-docs/README.md

@@ -0,0 +1,25 @@
+# Sidebar Manager — Internal Documentation
+
+> Auto-generated documentation for developer onboarding and AI agent understanding.
+
+## Quick Facts
+
+| Key | Value |
+|-----|-------|
+| **Plugin Name** | Sidebar Manager |
+| **Version** | 2.0.0 |
+| **Text Domain** | bsfsidebars |
+| **Main File** | `sidebar-manager.php` |
+| **PHP Files** | 12 |
+| **Build Tool** | Grunt |
+| **Stack** | WordPress Plugin (PHP) |
+
+## Description
+
+Create and manage custom sidebars with target rules.
+
+## 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/ai-agent-guide.md

@@ -0,0 +1,40 @@
+# AI Agent Guide — Sidebar Manager
+
+## Quick Start for AI Agents
+
+1. **Entry point:** Start at `sidebar-manager.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 `bsfsidebars` 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', 'bsfsidebars' )` or `esc_html__( 'text', 'bsfsidebars' )`
+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 `bsfsidebars` 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/architecture.md

@@ -0,0 +1,32 @@
+# Architecture — Sidebar Manager
+
+## Overview
+
+Sidebar Manager is a WordPress plugin that follows standard WordPress plugin architecture patterns.
+
+## Entry Point
+
+The plugin entry point is `sidebar-manager.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 `sidebar-manager.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/codebase-map.md

@@ -0,0 +1,26 @@
+# Codebase Map — Sidebar Manager
+
+## Directory Structure
+
+```
+sidebar-manager/
+├── sidebar-manager.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
+├── classes/class-bsf-sb-loader.php
+├── classes/class-bsf-sb-metabox.php
+├── classes/class-bsf-sb-post-type.php
+├── classes/class-bsf-sb-sidebar.php
+├── classes/class-bsf-sb-white-label.php
+├── classes/modules/target-rule/class-bsf-sb-target-rules-fields.php
+├── includes/white-label.php
+├── lib/notices/class-astra-notices.php
+├── sidebar-manager.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
+```