php-devops/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

This is the developer workspace orchestrator for Host UK - a federated monorepo containing 18 Laravel packages. This repo contains only configuration and setup scripts; actual code lives in packages/core-*/, each with its own CLAUDE.md.

For coding standards, architecture patterns, and Laravel-specific guidance, see the parent /Users/snider/Code/host-uk/CLAUDE.md.

.core/ Folder System

This workspace uses a .core/ folder for configuration and Claude Code integration:

.core/
├── workspace.yaml           # Active package, paths, settings
├── plugin/
│   ├── plugin.json          # Claude Code manifest
│   ├── skills/              # Context-aware skills
│   │   ├── workspace.md     # Multi-repo navigation
│   │   ├── switch-package.md
│   │   └── package-status.md
│   └── hooks/               # Command hooks
│       └── prefer-core.sh   # Suggest core CLI commands
└── docs/
    └── core-folder-spec.md  # Full .core/ specification

Active Package

The active package in .core/workspace.yaml determines where unified commands run:

active: core-php  # Commands like `core php test` target this package

When working from the workspace root, change this to work on a different package without navigating directories.

Skills

Skills in .core/plugin/skills/ provide context-aware guidance:

• workspace.md - Multi-repo navigation and commands
• switch-package.md - How to change the active package
• package-status.md - Checking status across repos

Specification

See .core/docs/core-folder-spec.md for the full specification that each package should follow.

Initial Setup

# macOS/Linux
git clone git@github.com:host-uk/core-devops.git && cd core-devops && make setup

Windows Setup

The core CLI is not yet available on Windows. Use these steps instead:

# 1. Install dependencies (PowerShell as Admin)
.\scripts\install-deps.ps1

# 2. Authenticate GitHub CLI
gh auth login -h github.com -p https -s workflow,repo,read:org,read:project,project

# 3. Clone all repos
.\scripts\clone-repos.ps1

# 4. Enable PHP extensions (edit C:\tools\php84\php.ini, uncomment these):
#    extension=curl
#    extension=fileinfo
#    extension=mbstring
#    extension=openssl
#    extension=pdo_sqlite

# 5. Install and test a package
cd packages/core-php
composer install
composer test

Environment Variables (macOS/Linux)

For install-core.sh:

• INSTALL_DIR - Binary location (default: ~/.local/bin)
• BUILD_FROM_SOURCE - true, false, or auto (default: auto, tries binary then builds)

Commands

Workspace-level (from root)

# Setup & diagnostics
make setup              # Full setup (deps + core CLI + clone repos)
core doctor             # Check environment health
core doctor --fix       # Attempt to fix issues

# Multi-repo workflow
core health             # Quick status summary
core work               # Full workflow: status → commit → push
core work --status      # Status table only
core commit             # Claude-assisted commits for dirty repos
core commit --all       # Commit all without prompting
core push               # Push repos with unpushed commits
core pull               # Pull repos that are behind

# GitHub integration (requires gh CLI)
core issues             # List open issues across repos
core issues --assignee @me
core reviews            # List PRs needing review
core ci                 # GitHub Actions workflow status

# Dependency analysis
core impact core-php    # Show what depends on core-php

Active package (from root)

core php test           # Run Pest tests in active package
core php lint           # Run Pint linter in active package
core php dev            # Start Vite dev server

Direct package work

cd packages/core-php
composer install && composer test           # Run Pest tests
composer test -- --filter=ClassName         # Single test
./vendor/bin/pint --dirty                   # Format changed files

Package Switching Workflow

To work on a different package without navigating:

1. Edit .core/workspace.yaml:

   active: core-tenant
   

2. Run commands from workspace root:

   core php test    # Now runs in core-tenant
   

3. Read the package's CLAUDE.md:

   cat packages/core-tenant/CLAUDE.md
   

Package Types

Defined in repos.yaml:

• foundation: core-php - base framework, no dependencies
• module: core-tenant, core-admin, core-api, core-mcp - infrastructure
• product: core-bio, core-social, etc. - user-facing apps
• template: core-template - starter for new projects
• meta: core-devops - this workspace repo

Troubleshooting

• "core: command not found" → make install-core (builds from https://github.com/host-uk/core)
• "gh: command not found" → brew install gh && gh auth login -h github.com -p https -s workflow,repo,read:org,read:project,project
• "refusing to allow..." or "missing required scopes" → gh auth refresh -h github.com -s workflow,read:project,project
• Clone failures → ssh -T git@github.com to verify SSH keys

Windows-Specific

• "openssl extension is required" → Enable extensions in C:\tools\php84\php.ini (see setup above)
• "composer: command not found" → Use PowerShell, not Git Bash: powershell -Command "composer install"
• core CLI not available → Use .\scripts\clone-repos.ps1 and work directly with composer

This Repo's Scope

Don't add application code here. This repo only contains:

• repos.yaml - Package registry with dependencies
• scripts/ - Cross-platform setup scripts (install-deps, install-core)
• Makefile - Setup orchestration
• .core/ - Workspace configuration and Claude Code integration