367 lines
14 KiB
Plaintext
367 lines
14 KiB
Plaintext
<!--
|
|
Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
|
|
|
|
This file is part of a Moko Consulting project.
|
|
|
|
SPDX-License-Identifier: GPL-3.0-or-later
|
|
|
|
# FILE INFORMATION
|
|
DEFGROUP: MokoStandards.Templates.GitHub
|
|
INGROUP: MokoStandards.Templates
|
|
REPO: https://git.mokoconsulting.tech/mokoconsulting-tech/MokoStandards-API
|
|
PATH: /templates/github/CLAUDE.md.template
|
|
VERSION: XX.YY.ZZ
|
|
BRIEF: Standard CLAUDE.md template for Moko Consulting governed repositories
|
|
NOTE: Synced to .github/CLAUDE.md in all governed repositories via bulk sync.
|
|
Tokens replaced at sync time: {{REPO_NAME}}, {{REPO_URL}}, {{PRIMARY_LANGUAGE}}, {{PLATFORM_TYPE}}, {{REPO_DESCRIPTION}}
|
|
-->
|
|
|
|
> [!IMPORTANT]
|
|
> **🔧 AI Self-Update Required on First Use**
|
|
>
|
|
> This file may contain unfilled `{{TOKEN}}` placeholders. The MokoStandards bulk-sync system
|
|
> replaces them automatically at sync time; if you can still see them, sync has not yet run for
|
|
> this repository — or this is a brand-new repo.
|
|
>
|
|
> **On your very first interaction in this repository, before answering any other question:**
|
|
>
|
|
> 1. Check whether any `{{TOKEN}}` placeholders remain in this file.
|
|
> 2. If they do, locate the values as described in the table below and replace every occurrence
|
|
> in **both** `.github/copilot-instructions.md` and `.github/CLAUDE.md`.
|
|
> 3. After replacing all tokens, **delete this entire notice block** (from `> [!IMPORTANT]`
|
|
> through the closing `> ---` line) in both files.
|
|
> 4. Tell the developer: *"I've self-updated the AI context files with this repository's
|
|
> values — all set."*
|
|
>
|
|
> | Placeholder | Where to find the value |
|
|
> |---|---|
|
|
> | `{{REPO_NAME}}` | The GitHub repository name (visible in the URL, `README.md` heading, or `git remote -v`) |
|
|
> | `{{REPO_URL}}` | Full GitHub URL, e.g. `https://git.mokoconsulting.tech/mokoconsulting-tech/<repo-name>` |
|
|
> | `{{REPO_DESCRIPTION}}` | First paragraph of `README.md` body, or the GitHub repo description |
|
|
> | `{{PRIMARY_LANGUAGE}}` | The dominant programming language (check file extensions in the repository) |
|
|
> | `{{PLATFORM_TYPE}}` | The project type: `PHP library`, `Joomla extension`, `Dolibarr module`, `WaaS site`, etc. — infer from repo structure |
|
|
>
|
|
> ---
|
|
|
|
# What This Repo Is
|
|
|
|
**{{REPO_NAME}}** is a Moko Consulting **{{PLATFORM_TYPE}}** repository.
|
|
|
|
{{REPO_DESCRIPTION}}
|
|
|
|
Repository URL: {{REPO_URL}}
|
|
|
|
This repository is governed by [MokoStandards](https://git.mokoconsulting.tech/mokoconsulting-tech/MokoStandards) — the single source of truth for coding standards, file-header policies, GitHub Actions workflows, and Terraform configuration templates across all Moko Consulting repositories.
|
|
|
|
---
|
|
|
|
# Repo Structure
|
|
|
|
```
|
|
{{REPO_NAME}}/
|
|
├── src/ # Primary source code
|
|
├── docs/ # Documentation
|
|
├── tests/ # Test suite
|
|
├── .github/
|
|
│ ├── workflows/ # CI/CD workflows (synced from MokoStandards)
|
|
│ ├── ISSUE_TEMPLATE/ # Issue templates (synced from MokoStandards)
|
|
│ ├── copilot-instructions.md # GitHub Copilot custom instructions
|
|
│ ├── CLAUDE.md # This file — Claude AI assistant context
|
|
│ └── override.tf # Repository-specific health-check overrides
|
|
├── README.md # Project overview — version source of truth
|
|
├── CHANGELOG.md # Version history
|
|
├── CONTRIBUTING.md # Contribution guidelines
|
|
└── LICENSE # GPL-3.0-or-later
|
|
```
|
|
|
|
---
|
|
|
|
# Primary Language
|
|
|
|
**{{PRIMARY_LANGUAGE}}** is the primary language for this repository.
|
|
|
|
YAML uses 2-space indentation (spaces, not tabs). All other text files use tabs per `.editorconfig`.
|
|
|
|
---
|
|
|
|
# Composer Package (PHP repositories)
|
|
|
|
This repository requires the MokoStandards enterprise library. The package is installed from the private GitHub VCS source.
|
|
|
|
`composer.json` must contain:
|
|
|
|
```json
|
|
{
|
|
"repositories": [
|
|
{
|
|
"type": "vcs",
|
|
"url": "https://git.mokoconsulting.tech/mokoconsulting-tech/MokoStandards"
|
|
}
|
|
],
|
|
"require": {
|
|
"mokoconsulting/mokostandards": "^4.0"
|
|
}
|
|
}
|
|
```
|
|
|
|
Install or update with:
|
|
|
|
```bash
|
|
composer install # first time
|
|
composer update mokoconsulting/mokostandards # upgrade
|
|
```
|
|
|
|
---
|
|
|
|
# PHP Script Pattern
|
|
|
|
All PHP scripts must extend `MokoStandards\Enterprise\CliFramework` — **never** use a standalone class or the legacy `CliBase`.
|
|
|
|
```php
|
|
#!/usr/bin/env php
|
|
<?php
|
|
/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
|
|
*
|
|
* This file is part of a Moko Consulting project.
|
|
*
|
|
* SPDX-License-Identifier: GPL-3.0-or-later
|
|
*
|
|
* FILE INFORMATION
|
|
* DEFGROUP: {{REPO_NAME}}.Scripts
|
|
* INGROUP: {{REPO_NAME}}
|
|
* REPO: {{REPO_URL}}
|
|
* PATH: /api/my_script.php
|
|
* VERSION: XX.YY.ZZ
|
|
* BRIEF: One-line description of what this script does
|
|
*/
|
|
|
|
declare(strict_types=1);
|
|
|
|
require_once __DIR__ . '/vendor/autoload.php';
|
|
|
|
use MokoStandards\Enterprise\CliFramework;
|
|
|
|
class MyScript extends CliFramework
|
|
{
|
|
protected function configure(): void
|
|
{
|
|
$this->setDescription('One-line description of what this script does');
|
|
$this->addArgument('--path', 'Repository root path', '.');
|
|
$this->addArgument('--dry-run', 'Preview changes without writing', false);
|
|
}
|
|
|
|
protected function run(): int
|
|
{
|
|
$path = $this->getArgument('--path');
|
|
$dryRun = (bool) $this->getArgument('--dry-run');
|
|
|
|
// implementation …
|
|
$this->log('INFO', "Processing: {$path}");
|
|
|
|
return 0;
|
|
}
|
|
}
|
|
|
|
$script = new MyScript('my_script', 'One-line description of what this script does');
|
|
exit($script->execute());
|
|
```
|
|
|
|
**CliFramework interface summary:**
|
|
|
|
| Member | Purpose |
|
|
|--------|---------|
|
|
| `configure(): void` | Abstract — register arguments with `addArgument()` |
|
|
| `run(): int` | Abstract — main script logic; return the exit code |
|
|
| `initialize(): void` | Optional hook — runs after arg-parse, before `run()` |
|
|
| `execute(array $argv = []): int` | **Public entry point** — call this at the bottom; it calls `configure()`, parses argv, then calls `run()` |
|
|
| `addArgument(string $name, string $desc, mixed $default)` | Register a CLI argument |
|
|
| `getArgument(string $name): mixed` | Read a parsed or default argument value |
|
|
| `log(string $level, string $message)` | Structured log — levels: INFO SUCCESS WARNING ERROR DEBUG |
|
|
| `error(string $message, int $code = 1): never` | Log error and exit |
|
|
| `$this->dryRun` | `true` when `--dry-run` is passed |
|
|
| `$this->verbose` | `true` when `--verbose` / `-v` is passed |
|
|
|
|
**Forbidden patterns in PHP:**
|
|
|
|
```php
|
|
// ❌ Wrong — legacy base class, not namespaced
|
|
class MyScript extends CliBase { … }
|
|
|
|
// ❌ Wrong — standalone class with no framework
|
|
class MyScript { public function run() { … } }
|
|
|
|
// ❌ Wrong — method names and entry-point transposed
|
|
protected function execute(): int { … } // should be run()
|
|
exit($script->run()); // should be execute()
|
|
|
|
// ✅ Correct
|
|
class MyScript extends CliFramework {
|
|
protected function configure(): void { … }
|
|
protected function run(): int { … }
|
|
}
|
|
$script = new MyScript('name', 'description');
|
|
exit($script->execute());
|
|
```
|
|
|
|
---
|
|
|
|
# Version Management
|
|
|
|
**`README.md` is the single source of truth for the repository version.**
|
|
|
|
- **Bump the patch version on every PR** — increment `XX.YY.ZZ` (e.g. `01.02.03` → `01.02.04`) in `README.md` before opening the PR; the `sync-version-on-merge` workflow propagates it to all badges and `FILE INFORMATION` headers automatically on merge to `main`.
|
|
- The `VERSION: XX.YY.ZZ` field in the `README.md` `FILE INFORMATION` block governs all other version references.
|
|
- Update `README.md` only — the `sync-version-on-merge` workflow propagates it to all badges and `FILE INFORMATION` headers automatically on merge to `main`.
|
|
- Version format is zero-padded semver: `XX.YY.ZZ` (e.g. `01.02.03`).
|
|
- Never hardcode a version number in body text — use the badge or FILE INFORMATION header only.
|
|
|
|
---
|
|
|
|
# File Header Requirements
|
|
|
|
Every new file **must** have a copyright header as its first content. JSON files, binary files, generated files, and third-party files are exempt.
|
|
|
|
## Minimal header
|
|
|
|
**PHP:**
|
|
```php
|
|
<?php
|
|
/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
|
|
*
|
|
* This file is part of a Moko Consulting project.
|
|
*
|
|
* SPDX-License-Identifier: GPL-3.0-or-later
|
|
*
|
|
* FILE INFORMATION
|
|
* DEFGROUP: {{REPO_NAME}}.Module
|
|
* INGROUP: {{REPO_NAME}}
|
|
* REPO: {{REPO_URL}}
|
|
* PATH: /src/MyClass.php
|
|
* VERSION: XX.YY.ZZ
|
|
* BRIEF: One-line description of file purpose
|
|
*/
|
|
|
|
declare(strict_types=1);
|
|
```
|
|
|
|
**Markdown:**
|
|
```markdown
|
|
<!--
|
|
Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
|
|
|
|
This file is part of a Moko Consulting project.
|
|
|
|
SPDX-License-Identifier: GPL-3.0-or-later
|
|
|
|
# FILE INFORMATION
|
|
DEFGROUP: {{REPO_NAME}}.Documentation
|
|
INGROUP: {{REPO_NAME}}
|
|
REPO: {{REPO_URL}}
|
|
PATH: /docs/guide/example.md
|
|
VERSION: XX.YY.ZZ
|
|
BRIEF: One-line description of file purpose
|
|
-->
|
|
```
|
|
|
|
**YAML / Shell:** Use `#` comments with the same fields. JSON files are exempt.
|
|
|
|
---
|
|
|
|
# Coding Standards
|
|
|
|
## Naming Conventions
|
|
|
|
| Context | Convention | Example |
|
|
|---------|-----------|---------|
|
|
| PHP class | `PascalCase` | `MyService` |
|
|
| PHP method / function | `camelCase` | `getUserData()` |
|
|
| PHP variable | `$snake_case` | `$user_id` |
|
|
| PHP constant | `UPPER_SNAKE_CASE` | `MAX_RETRIES` |
|
|
| PHP class file | `PascalCase.php` | `UserService.php` |
|
|
| PHP script file | `snake_case.php` | `check_health.php` |
|
|
| YAML workflow | `kebab-case.yml` | `code-quality.yml` |
|
|
| Markdown doc | `kebab-case.md` | `coding-style-guide.md` |
|
|
|
|
## Commit Messages
|
|
|
|
Format: `<type>(<scope>): <subject>` — imperative, lower-case subject, no trailing period.
|
|
|
|
Valid types: `feat` · `fix` · `docs` · `chore` · `ci` · `refactor` · `style` · `test` · `perf` · `revert` · `build`
|
|
|
|
## Branch Naming
|
|
|
|
Format: `<prefix>/<MAJOR.MINOR.PATCH>[/description]`
|
|
|
|
Approved prefixes: `dev/` · `rc/` · `version/` · `patch/` · `copilot/` · `dependabot/`
|
|
|
|
---
|
|
|
|
# GitHub Actions — Token Usage
|
|
|
|
Every workflow in this repository must use **`secrets.GH_TOKEN`** (the org-level Personal Access Token).
|
|
|
|
```yaml
|
|
# ✅ Correct — always use GH_TOKEN
|
|
- uses: actions/checkout@v4
|
|
with:
|
|
token: ${{ secrets.GH_TOKEN }}
|
|
|
|
env:
|
|
GH_TOKEN: ${{ secrets.GH_TOKEN }}
|
|
```
|
|
|
|
```yaml
|
|
# ❌ Wrong — never use these
|
|
token: ${{ github.token }}
|
|
token: ${{ secrets.GITHUB_TOKEN }}
|
|
```
|
|
|
|
PHP scripts read the token with: `getenv('GH_TOKEN') ?: getenv('GITHUB_TOKEN')` — `GH_TOKEN` is always preferred; `GITHUB_TOKEN` is a local-dev fallback only.
|
|
|
|
---
|
|
|
|
# Keeping Documentation Current
|
|
|
|
Whenever you make code changes, update the corresponding documentation in the same commit or PR. Do not leave docs stale.
|
|
|
|
| Change type | Documentation to update |
|
|
|-------------|------------------------|
|
|
| New or renamed public PHP method | PHPDoc block on the method; `docs/api/` index for that class |
|
|
| New or changed CLI script argument | Script's own `--help` text; `docs/api/` or equivalent |
|
|
| New or changed GitHub Actions workflow | `docs/workflows/<workflow-name>.md` |
|
|
| New or changed policy | Corresponding file under `docs/policy/` |
|
|
| New library class or major feature | `CHANGELOG.md` entry under `Added` |
|
|
| Bug fix | `CHANGELOG.md` entry under `Fixed` |
|
|
| Breaking change | `CHANGELOG.md` entry under `Changed`; update `CONTRIBUTING.md` if contributor steps change |
|
|
| Any modified file | Update the `VERSION` field in that file's `FILE INFORMATION` block |
|
|
| **Every PR** | **Bump the patch version** — increment `XX.YY.ZZ` in `README.md`; `sync-version-on-merge` propagates it to all headers and badges on merge |
|
|
|
|
If your code change makes any existing doc sentence false or incomplete, fix the doc before closing the PR.
|
|
|
|
---
|
|
|
|
# What NOT to Do
|
|
|
|
- **Never commit directly to `main`** — all changes go through a PR.
|
|
- **Never hardcode version numbers** in body text — update `README.md` and let automation propagate.
|
|
- **Never skip the FILE INFORMATION block** on a new source file.
|
|
- **Never use bare `catch (\Throwable $e) {}`** — always log or re-throw.
|
|
- **Never mix tabs and spaces** within a file — follow `.editorconfig`.
|
|
- **Never use `github.token` or `secrets.GITHUB_TOKEN` in workflows** — always use `secrets.GH_TOKEN`.
|
|
- **Never extend `CliBase` in PHP scripts** — extend `MokoStandards\Enterprise\CliFramework` instead.
|
|
- **Never use `exit($script->run())`** — the correct entry point is `exit($script->execute())`.
|
|
|
|
---
|
|
|
|
# Key Policy Documents (MokoStandards)
|
|
|
|
| Document | Purpose |
|
|
|----------|---------|
|
|
| [file-header-standards.md](https://git.mokoconsulting.tech/mokoconsulting-tech/MokoStandards/blob/main/docs/policy/file-header-standards.md) | Copyright-header rules for every file type |
|
|
| [coding-style-guide.md](https://git.mokoconsulting.tech/mokoconsulting-tech/MokoStandards/blob/main/docs/policy/coding-style-guide.md) | Naming and formatting conventions |
|
|
| [branching-strategy.md](https://git.mokoconsulting.tech/mokoconsulting-tech/MokoStandards/blob/main/docs/policy/branching-strategy.md) | Branch naming, hierarchy, and release workflow |
|
|
| [merge-strategy.md](https://git.mokoconsulting.tech/mokoconsulting-tech/MokoStandards/blob/main/docs/policy/merge-strategy.md) | Squash-merge policy and PR conventions |
|
|
| [changelog-standards.md](https://git.mokoconsulting.tech/mokoconsulting-tech/MokoStandards/blob/main/docs/policy/changelog-standards.md) | How and when to update CHANGELOG.md |
|
|
| [scripting-standards.md](https://git.mokoconsulting.tech/mokoconsulting-tech/MokoStandards/blob/main/docs/policy/scripting-standards.md) | PHP script requirements and CliFramework usage |
|
|
| [package-installation.md](https://git.mokoconsulting.tech/mokoconsulting-tech/MokoStandards/blob/main/docs/guide/package-installation.md) | Installing `mokoconsulting/mokostandards` via Composer |
|