Skip to content

Commit ecfb741

Browse files
kiransbsfkiransbsf
authored
Merge pull request #152 from brainstormforce/claude-docs-setup
chore: add Claude Code scaffolding and internal docs
2 parents 929fa0e + b3aedae commit ecfb741

9 files changed

Lines changed: 226 additions & 0 deletions

File tree

‎.claude/settings.json‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
{
2+
"permissions": {
3+
"allow": [
4+
"Bash(npx grunt:*)",
5+
"Bash(npm install)",
6+
"Bash(composer install)",
7+
"Bash(./vendor/bin/phpcs:*)",
8+
"Bash(git status)",
9+
"Bash(git diff:*)",
10+
"Bash(git log:*)",
11+
"Bash(git branch:*)",
12+
"Bash(git checkout:*)",
13+
"Bash(git add:*)",
14+
"Bash(git commit:*)",
15+
"Bash(git push:*)",
16+
"Bash(git remote:*)",
17+
"Bash(ls:*)",
18+
"Bash(find:*)",
19+
"Bash(cat:*)",
20+
"Bash(wc:*)"
21+
],
22+
"deny": [
23+
"Bash(rm -rf:*)",
24+
"Bash(git push --force:*)",
25+
"Bash(git reset --hard:*)"
26+
]
27+
}
28+
}

‎.distignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,3 +31,7 @@ node_modules
3131
*.zip
3232
.github
3333
.wordpress-org
34+
35+
.claude
36+
CLAUDE.md
37+
internal-docs

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,3 +33,5 @@ no-toggle-border-fix.json
3333

3434
# Large dist directory - Build files can be in MBs, let's not increase size of the git repo
3535
admin/dashboard/assets/build/
36+
37+
.claude/settings.local.json

‎CLAUDE.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Custom Fonts
2+
3+
## Project Overview
4+
5+
Custom Fonts is a WordPress plugin by Brainstorm Force. Upload custom fonts or host Google fonts locally for performance, privacy, and full site editing support.
6+
7+
- **Version:** 2.1.17
8+
- **Text Domain:** custom-fonts
9+
- **Main File:** custom-fonts.php
10+
- **Requires:** WordPress, PHP 5.6+
11+
12+
## Tech Stack
13+
14+
- **Language:** PHP
15+
- **Platform:** WordPress
16+
- **Build:** Grunt (i18n, readme conversion)
17+
- **Coding Standards:** PHPCS with WordPress standards
18+
19+
## Commands
20+
21+
```bash
22+
# Install dependencies
23+
npm install
24+
composer install
25+
26+
# Build (i18n + readme)
27+
npx grunt
28+
29+
# Generate translations
30+
npx grunt i18n
31+
32+
# Convert readme.txt to README.md
33+
npx grunt readme
34+
35+
# Run PHPCS
36+
./vendor/bin/phpcs .
37+
```
38+
39+
## Architecture
40+
41+
This is a WordPress plugin following standard WordPress patterns:
42+
- Entry point: `custom-fonts.php`
43+
- Constants defined for version, file path, base, dir, and URI
44+
- Classes loaded via `after_setup_theme` or `plugins_loaded` hook
45+
- Follows WordPress Coding Standards (WPCS)
46+
47+
## Conventions
48+
49+
- Use WordPress hooks (`add_action`, `add_filter`) for extensibility
50+
- Prefix all functions and classes to avoid conflicts
51+
- Use `custom-fonts` text domain for all translatable strings
52+
- Escape all output (`esc_html`, `esc_attr`, `esc_url`, `wp_kses`)
53+
- Sanitize all input (`sanitize_text_field`, `absint`, etc.)
54+
- Use nonces for form submissions and AJAX requests
55+
- Follow WordPress PHP coding standards

‎Gruntfile.js‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,9 @@ module.exports = function( grunt ) {
114114
'!phpcs.xml',
115115
'!phpcs.xml.dist',
116116
'!admin/dashboard/assets/src/**',
117+
'!CLAUDE.md',
118+
'!.claude/**',
119+
'!internal-docs/**',
117120
],
118121
dest: 'custom-fonts/'
119122
}

‎internal-docs/README.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Custom Fonts — Internal Documentation
2+
3+
> Auto-generated documentation for developer onboarding and AI agent understanding.
4+
5+
## Quick Facts
6+
7+
| Key | Value |
8+
|-----|-------|
9+
| **Plugin Name** | Custom Fonts |
10+
| **Version** | 2.1.17 |
11+
| **Text Domain** | custom-fonts |
12+
| **Main File** | `custom-fonts.php` |
13+
| **PHP Files** | 23 |
14+
| **Build Tool** | Grunt |
15+
| **Stack** | WordPress Plugin (PHP) |
16+
17+
## Description
18+
19+
Upload custom fonts or host Google fonts locally for performance, privacy, and full site editing support.
20+
21+
## Index
22+
23+
- [Architecture](architecture.md) — High-level architecture and data flow
24+
- [Codebase Map](codebase-map.md) — Directory structure and key files
25+
- [AI Agent Guide](ai-agent-guide.md) — Key patterns and locations for AI-assisted development

‎internal-docs/ai-agent-guide.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# AI Agent Guide — Custom Fonts
2+
3+
## Quick Start for AI Agents
4+
5+
1. **Entry point:** Start at `custom-fonts.php` to understand plugin initialization
6+
2. **Constants:** Look for `define()` calls in the main file for paths and versions
7+
3. **Hook registration:** Search for `add_action` and `add_filter` to find where functionality is attached
8+
4. **Text domain:** Use `custom-fonts` for all translatable strings
9+
10+
## Common Tasks
11+
12+
### Adding a new feature
13+
1. Create a new class file in the appropriate directory
14+
2. Register it via `require_once` in the loader or main class
15+
3. Use `add_action`/`add_filter` to hook into WordPress
16+
4. Follow existing class patterns for consistency
17+
18+
### Modifying existing behavior
19+
1. Find the relevant class by searching for the hook or function name
20+
2. Check for filters that allow modification without editing core files
21+
3. If editing, maintain the existing code style and patterns
22+
23+
### Adding translatable strings
24+
1. Wrap strings in `__( 'text', 'custom-fonts' )` or `esc_html__( 'text', 'custom-fonts' )`
25+
2. Run `npx grunt i18n` to update the POT file
26+
27+
## WordPress Checklist
28+
29+
- [ ] All output is escaped (`esc_html`, `esc_attr`, `esc_url`, `wp_kses`)
30+
- [ ] All input is sanitized (`sanitize_text_field`, `absint`, etc.)
31+
- [ ] Nonces used for forms and AJAX (`wp_nonce_field`, `check_ajax_referer`)
32+
- [ ] Capability checks before privileged operations (`current_user_can`)
33+
- [ ] Text domain `custom-fonts` used for all user-facing strings
34+
- [ ] No direct file access (files start with `defined( 'ABSPATH' )` check or silence)
35+
36+
## Pitfalls
37+
38+
- Plugin may depend on Astra theme being active — check for theme dependency logic
39+
- Constants are defined only once — don't redefine them
40+
- Follow WordPress coding standards (spaces not tabs for alignment, tabs for indentation)

‎internal-docs/architecture.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Architecture — Custom Fonts
2+
3+
## Overview
4+
5+
Custom Fonts is a WordPress plugin that follows standard WordPress plugin architecture patterns.
6+
7+
## Entry Point
8+
9+
The plugin entry point is `custom-fonts.php`, which:
10+
1. Defines plugin constants (version, file path, base name, directory, URI)
11+
2. Loads the main plugin class via a WordPress hook (`after_setup_theme` or `plugins_loaded`)
12+
13+
## Request Lifecycle
14+
15+
1. WordPress loads the plugin via `custom-fonts.php`
16+
2. Constants are defined for use throughout the plugin
17+
3. Main class is instantiated/loaded on the appropriate hook
18+
4. Classes register their own hooks and filters
19+
5. Frontend/admin output is rendered when WordPress fires the relevant hooks
20+
21+
## Key Patterns
22+
23+
- **Hook-based architecture:** All functionality is attached via `add_action()` and `add_filter()`
24+
- **Class autoloading:** Classes are loaded via `require_once` in the main plugin file or loader class
25+
- **Separation of concerns:** Admin and frontend code are separated into different classes/directories
26+
- **WordPress Customizer integration:** Settings are registered via the Customizer API where applicable
27+
28+
## Dependencies
29+
30+
- WordPress core (required)
31+
- Astra theme (recommended/required for full functionality)
32+
- No external PHP dependencies beyond WordPress

‎internal-docs/codebase-map.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Codebase Map — Custom Fonts
2+
3+
## Directory Structure
4+
5+
```
6+
custom-fonts/
7+
├── custom-fonts.php # Plugin entry point
8+
├── admin/bsf-analytics/class-bsf-analytics-loader.php
9+
├── admin/bsf-analytics/class-bsf-analytics-stats.php
10+
├── admin/bsf-analytics/class-bsf-analytics.php
11+
├── admin/dashboard/class-bsf-custom-font-admin-loader.php
12+
├── admin/dashboard/includes/class-bcf-custom-font-families.php
13+
├── admin/dashboard/includes/class-bsf-custom-fonts-admin-ajax.php
14+
├── admin/dashboard/includes/class-bsf-custom-fonts-menu.php
15+
├── assets/fonts/google-fonts.php
16+
├── classes/class-bsf-custom-fonts-render.php
17+
├── classes/class-bsf-custom-fonts-white-label.php
18+
├── classes/class-bsf-custom-fonts.php
19+
├── custom-fonts.php
20+
├── includes/class-bcf-filesystem.php
21+
├── includes/class-bcf-google-fonts-compatibility.php
22+
├── includes/class-bsf-custom-fonts-admin.php
23+
├── includes/class-bsf-custom-fonts-posttype.php
24+
├── includes/class-bsf-custom-fonts-taxonomy.php
25+
├── includes/class-custom-fonts-api-init.php
26+
├── includes/helper-functions.php
27+
├── includes/plugin-update/class-custom-fonts-update.php
28+
├── includes/rest-api/class-cf-bsf-analytics-compatibility.php
29+
├── includes/white-label.php
30+
├── lib/notices/class-astra-notices.php
31+
├── .distignore # WordPress.org distribution exclusions
32+
├── .gitignore # Git exclusions
33+
├── Gruntfile.js # Grunt build configuration
34+
├── package.json # Node.js dependencies
35+
├── CLAUDE.md # Claude Code project context
36+
└── .claude/settings.json # Claude Code tool permissions
37+
```

0 commit comments

Comments
 (0)