MokoConsulting/MokoCLI
Public Access
1
0
Fork 0
Code Issues 1 Pull Requests Releases 8 Wiki Activity

chore: update CLAUDE.md template with first-run setup and focused format

Browse Source 
Replace verbose boilerplate with platform-specific scaffold including
first-run setup checklist and placeholder tokens for new repos.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jonathan Miller
2026-06-06 10:01:27 -05:00
parent 6e40707223
commit 9df59836bf
1 changed files with 22 additions and 354 deletions
Download Patch File Download Diff File Expand all files Collapse all files
templates/mokogitea/CLAUDE.md.template
+22 -354
View File
@@ -1,366 +1,34 @@
<!--
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: MokoPlatform.Templates.GitHub
INGROUP: MokoPlatform.Templates
REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
PATH: /templates/mokogitea/CLAUDE.md.template
VERSION: XX.YY.ZZ
BRIEF: Standard CLAUDE.md template for Moko Consulting governed repositories
NOTE: Synced to .gitea/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 moko-platform 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** `.gitea/copilot-instructions.md` and `.gitea/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_NAME}}
{{REPO_DESCRIPTION}}
Repository URL: {{REPO_URL}}
## Quick Reference
This repository is governed by [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) — the single source of truth for coding standards, file-header policies, GitHub Actions workflows, and Terraform configuration templates across all Moko Consulting repositories.
| Field | Value |
|---|---|
| **Platform** | {{PLATFORM_TYPE}} |
| **Language** | {{PRIMARY_LANGUAGE}} |
| **Branch** | develop on `dev`, merge to `main` (protected) |
| **Wiki** | [{{REPO_NAME}} Wiki](https://git.mokoconsulting.tech/MokoConsulting/{{REPO_NAME}}/wiki) |
---
# Repo Structure
```
{{REPO_NAME}}/
├── src/ # Primary source code
├── docs/ # Documentation
├── tests/ # Test suite
├── .gitea/
│ ├── workflows/ # CI/CD workflows (synced from moko-platform)
│ ├── ISSUE_TEMPLATE/ # Issue templates (synced from moko-platform)
│ ├── 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 moko-platform 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/moko-platform"
}
],
"require": {
"mokoconsulting/mokostandards": "^4.0"
}
}
```
Install or update with:
## Commands
```bash
composer install # first time
composer update mokoconsulting/mokostandards # upgrade
make build # Build the project
make lint # Run linters
make validate # Validate structure
make release # Full release pipeline
make clean # Clean build artifacts
```
---
## Architecture
# PHP Script Pattern
<!-- Platform-specific: update this section for each repo -->
All PHP scripts must extend `MokoStandards\Enterprise\CliFramework` — **never** use a standalone class or the legacy `CliBase`.
## Rules
```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 (moko-platform)
| Document | Purpose |
|----------|---------|
| [file-header-standards.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/policy/file-header-standards.md) | Copyright-header rules for every file type |
| [coding-style-guide.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/policy/coding-style-guide.md) | Naming and formatting conventions |
| [branching-strategy.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/policy/branching-strategy.md) | Branch naming, hierarchy, and release workflow |
| [merge-strategy.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/policy/merge-strategy.md) | Squash-merge policy and PR conventions |
| [changelog-standards.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/policy/changelog-standards.md) | How and when to update CHANGELOG.md |
| [scripting-standards.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/policy/scripting-standards.md) | PHP script requirements and CliFramework usage |
| [package-installation.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/guide/package-installation.md) | Installing `mokoconsulting/mokostandards` via Composer |
- **Never commit** `.claude/`, `.mcp.json`, `TODO.md`, `*.min.css`/`*.min.js`
- **Attribution**: `Authored-by: Moko Consulting`
- **Workflow directory**: `.mokogitea/` (not `.gitea/` or `.github/`)
- **Wiki**: documentation lives in the Gitea wiki, not `docs/` files
- **Standards**: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)