feat: add .core/ bridge system for fresh developer onboarding
Introduces a .core/ folder structure that provides: - workspace.yaml for active package configuration - Claude Code plugin with skills for multi-repo navigation - Hook script suggesting core CLI over raw commands - Full .core/ folder specification for other packages Also restructures README.md and CLAUDE.md for better fresh developer experience with clear "what happens" and "what's next" sections. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Snider
parent
cd79af256c
commit
9600277897
10 changed files with 896 additions and 87 deletions
319
.core/docs/core-folder-spec.md
Normal file
319
.core/docs/core-folder-spec.md
Normal file
|
|
@ -0,0 +1,319 @@
|
|||
# .core/ Folder Specification
|
||||
|
||||
This document defines the `.core/` folder structure used across Host UK packages for configuration, tooling integration, and development environment setup.
|
||||
|
||||
## Overview
|
||||
|
||||
The `.core/` folder provides a standardised location for:
|
||||
- Build and development configuration
|
||||
- Claude Code plugin integration
|
||||
- VM/container definitions
|
||||
- Development environment settings
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
package/.core/
|
||||
├── config.yaml # Build targets, test commands, deploy config
|
||||
├── workspace.yaml # Workspace-level config (devops repo only)
|
||||
├── plugin/ # Claude Code integration
|
||||
│ ├── plugin.json # Plugin manifest
|
||||
│ ├── skills/ # Context-aware skills
|
||||
│ └── hooks/ # Pre/post command hooks
|
||||
├── linuxkit/ # VM/container definitions (if applicable)
|
||||
│ ├── kernel.yaml
|
||||
│ └── image.yaml
|
||||
└── run.yaml # Development environment config
|
||||
```
|
||||
|
||||
## Configuration Files
|
||||
|
||||
### config.yaml
|
||||
|
||||
Package-level build and runtime configuration.
|
||||
|
||||
```yaml
|
||||
version: 1
|
||||
|
||||
# Build configuration
|
||||
build:
|
||||
targets:
|
||||
- name: default
|
||||
command: composer build
|
||||
- name: production
|
||||
command: composer build:prod
|
||||
env:
|
||||
APP_ENV: production
|
||||
|
||||
# Test configuration
|
||||
test:
|
||||
command: composer test
|
||||
coverage: true
|
||||
parallel: true
|
||||
|
||||
# Lint configuration
|
||||
lint:
|
||||
command: ./vendor/bin/pint
|
||||
fix_command: ./vendor/bin/pint --dirty
|
||||
|
||||
# Deploy configuration (if applicable)
|
||||
deploy:
|
||||
staging:
|
||||
command: ./deploy.sh staging
|
||||
production:
|
||||
command: ./deploy.sh production
|
||||
requires_approval: true
|
||||
```
|
||||
|
||||
### workspace.yaml
|
||||
|
||||
Workspace-level configuration (only in `core-devops`).
|
||||
|
||||
```yaml
|
||||
version: 1
|
||||
|
||||
# Active package for unified commands
|
||||
active: core-php
|
||||
|
||||
# Default package types for setup
|
||||
default_only:
|
||||
- foundation
|
||||
- module
|
||||
|
||||
# Paths
|
||||
packages_dir: ./packages
|
||||
|
||||
# Workspace settings
|
||||
settings:
|
||||
suggest_core_commands: true
|
||||
show_active_in_prompt: true
|
||||
```
|
||||
|
||||
### run.yaml
|
||||
|
||||
Development environment configuration.
|
||||
|
||||
```yaml
|
||||
version: 1
|
||||
|
||||
# Services required for development
|
||||
services:
|
||||
- name: database
|
||||
image: postgres:16
|
||||
port: 5432
|
||||
env:
|
||||
POSTGRES_DB: core_dev
|
||||
POSTGRES_USER: core
|
||||
POSTGRES_PASSWORD: secret
|
||||
|
||||
- name: redis
|
||||
image: redis:7
|
||||
port: 6379
|
||||
|
||||
- name: mailpit
|
||||
image: axllent/mailpit
|
||||
port: 8025
|
||||
|
||||
# Development server
|
||||
dev:
|
||||
command: php artisan serve
|
||||
port: 8000
|
||||
watch:
|
||||
- app/
|
||||
- resources/
|
||||
|
||||
# Environment variables
|
||||
env:
|
||||
APP_ENV: local
|
||||
APP_DEBUG: true
|
||||
DB_CONNECTION: pgsql
|
||||
```
|
||||
|
||||
## Claude Code Plugin
|
||||
|
||||
### plugin.json
|
||||
|
||||
The plugin manifest defines skills, hooks, and commands for Claude Code integration.
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://claude.ai/code/plugin-schema.json",
|
||||
"name": "package-name",
|
||||
"version": "1.0.0",
|
||||
"description": "Claude Code integration for this package",
|
||||
|
||||
"skills": [
|
||||
{
|
||||
"name": "skill-name",
|
||||
"file": "skills/skill-name.md",
|
||||
"description": "What this skill provides"
|
||||
}
|
||||
],
|
||||
|
||||
"hooks": {
|
||||
"pre_command": [
|
||||
{
|
||||
"pattern": "^command-pattern$",
|
||||
"script": "hooks/script.sh",
|
||||
"description": "What this hook does"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"commands": {
|
||||
"command-name": {
|
||||
"description": "What this command does",
|
||||
"run": "actual-command"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Skills (skills/*.md)
|
||||
|
||||
Markdown files providing context-aware guidance for Claude Code. Skills are loaded when relevant to the user's query.
|
||||
|
||||
```markdown
|
||||
# Skill Name
|
||||
|
||||
Describe what this skill provides.
|
||||
|
||||
## Context
|
||||
|
||||
When to use this skill.
|
||||
|
||||
## Commands
|
||||
|
||||
Relevant commands and examples.
|
||||
|
||||
## Tips
|
||||
|
||||
Best practices and gotchas.
|
||||
```
|
||||
|
||||
### Hooks (hooks/*.sh)
|
||||
|
||||
Shell scripts executed before or after commands. Hooks should:
|
||||
- Be executable (`chmod +x`)
|
||||
- Exit 0 for informational hooks (don't block)
|
||||
- Exit non-zero to block the command (with reason)
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
|
||||
# Hook logic here
|
||||
|
||||
exit 0 # Don't block
|
||||
```
|
||||
|
||||
## LinuxKit (linuxkit/)
|
||||
|
||||
For packages that deploy as VMs or containers.
|
||||
|
||||
### kernel.yaml
|
||||
|
||||
```yaml
|
||||
kernel:
|
||||
image: linuxkit/kernel:6.6
|
||||
cmdline: "console=tty0"
|
||||
```
|
||||
|
||||
### image.yaml
|
||||
|
||||
```yaml
|
||||
image:
|
||||
- linuxkit/init:v1.0.1
|
||||
- linuxkit/runc:v1.0.0
|
||||
- linuxkit/containerd:v1.0.0
|
||||
```
|
||||
|
||||
## Package-Type Specific Patterns
|
||||
|
||||
### Foundation (core-php)
|
||||
|
||||
```
|
||||
core-php/.core/
|
||||
├── config.yaml # Build targets for framework
|
||||
├── plugin/
|
||||
│ └── skills/
|
||||
│ ├── events.md # Event system guidance
|
||||
│ ├── modules.md # Module loading patterns
|
||||
│ └── lifecycle.md # Lifecycle events
|
||||
└── run.yaml # Test environment setup
|
||||
```
|
||||
|
||||
### Module (core-tenant, core-admin, etc.)
|
||||
|
||||
```
|
||||
core-tenant/.core/
|
||||
├── config.yaml # Module-specific build
|
||||
├── plugin/
|
||||
│ └── skills/
|
||||
│ └── tenancy.md # Multi-tenancy patterns
|
||||
└── run.yaml # Required services (database)
|
||||
```
|
||||
|
||||
### Product (core-bio, core-social, etc.)
|
||||
|
||||
```
|
||||
core-bio/.core/
|
||||
├── config.yaml # Build and deploy targets
|
||||
├── plugin/
|
||||
│ └── skills/
|
||||
│ └── bio.md # Product-specific guidance
|
||||
├── linuxkit/ # VM definitions for deployment
|
||||
│ ├── kernel.yaml
|
||||
│ └── image.yaml
|
||||
└── run.yaml # Full dev environment
|
||||
```
|
||||
|
||||
### Workspace (core-devops)
|
||||
|
||||
```
|
||||
core-devops/.core/
|
||||
├── workspace.yaml # Active package, paths
|
||||
├── plugin/
|
||||
│ ├── plugin.json
|
||||
│ └── skills/
|
||||
│ ├── workspace.md # Multi-repo navigation
|
||||
│ ├── switch-package.md # Package switching
|
||||
│ └── package-status.md # Status checking
|
||||
└── docs/
|
||||
└── core-folder-spec.md # This file
|
||||
```
|
||||
|
||||
## Core CLI Integration
|
||||
|
||||
The `core` CLI reads configuration from `.core/`:
|
||||
|
||||
| File | CLI Command | Purpose |
|
||||
|------|-------------|---------|
|
||||
| `workspace.yaml` | `core workspace` | Active package, paths |
|
||||
| `config.yaml` | `core build`, `core test` | Build/test commands |
|
||||
| `run.yaml` | `core run` | Dev environment |
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always include `version: 1`** in YAML files for future compatibility
|
||||
2. **Keep skills focused** - one concept per skill file
|
||||
3. **Hooks should be fast** - don't slow down commands
|
||||
4. **Use relative paths** - avoid hardcoded absolute paths
|
||||
5. **Document non-obvious settings** with inline comments
|
||||
|
||||
## Migration Guide
|
||||
|
||||
To add `.core/` to an existing package:
|
||||
|
||||
1. Create the directory structure:
|
||||
```bash
|
||||
mkdir -p .core/plugin/skills .core/plugin/hooks
|
||||
```
|
||||
|
||||
2. Add `config.yaml` with build/test commands
|
||||
|
||||
3. Add `plugin.json` with package-specific skills
|
||||
|
||||
4. Add relevant skills in `skills/`
|
||||
|
||||
5. Update `.gitignore` if needed (don't ignore `.core/`)
|
||||
43
.core/plugin/hooks/prefer-core.sh
Executable file
43
.core/plugin/hooks/prefer-core.sh
Executable file
|
|
@ -0,0 +1,43 @@
|
|||
#!/bin/bash
|
||||
# prefer-core.sh - Suggest core CLI commands over raw commands
|
||||
#
|
||||
# This hook is called before certain commands to suggest core CLI equivalents.
|
||||
# It's informational only and doesn't block the original command.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
COMMAND="${1:-}"
|
||||
|
||||
suggest() {
|
||||
echo ""
|
||||
echo "💡 Tip: Consider using the core CLI instead:"
|
||||
echo " $1"
|
||||
echo ""
|
||||
}
|
||||
|
||||
case "$COMMAND" in
|
||||
"git add"*)
|
||||
suggest "core commit (stages and commits with Claude-assisted messages)"
|
||||
;;
|
||||
"git commit"*)
|
||||
suggest "core commit (Claude-assisted commit messages)"
|
||||
;;
|
||||
"git push"*)
|
||||
suggest "core push (pushes all repos with unpushed commits)"
|
||||
;;
|
||||
"git pull"*)
|
||||
suggest "core pull (pulls all repos that are behind)"
|
||||
;;
|
||||
"composer test"*)
|
||||
suggest "core php test (runs from workspace root, targets active package)"
|
||||
;;
|
||||
"composer lint"*)
|
||||
suggest "core php lint (runs from workspace root, targets active package)"
|
||||
;;
|
||||
*)
|
||||
# No suggestion for this command
|
||||
;;
|
||||
esac
|
||||
|
||||
# Always exit 0 - this is informational, not blocking
|
||||
exit 0
|
||||
55
.core/plugin/plugin.json
Normal file
55
.core/plugin/plugin.json
Normal file
|
|
@ -0,0 +1,55 @@
|
|||
{
|
||||
"$schema": "https://claude.ai/code/plugin-schema.json",
|
||||
"name": "host-uk-workspace",
|
||||
"version": "1.0.0",
|
||||
"description": "Claude Code integration for Host UK developer workspace",
|
||||
|
||||
"skills": [
|
||||
{
|
||||
"name": "workspace",
|
||||
"file": "skills/workspace.md",
|
||||
"description": "Navigate and manage the Host UK multi-repo workspace"
|
||||
},
|
||||
{
|
||||
"name": "switch-package",
|
||||
"file": "skills/switch-package.md",
|
||||
"description": "Switch the active package for core CLI commands"
|
||||
},
|
||||
{
|
||||
"name": "package-status",
|
||||
"file": "skills/package-status.md",
|
||||
"description": "Show status of all packages in the workspace"
|
||||
}
|
||||
],
|
||||
|
||||
"hooks": {
|
||||
"pre_command": [
|
||||
{
|
||||
"pattern": "^(git (add|commit|push|pull)|composer (test|lint))$",
|
||||
"script": "hooks/prefer-core.sh",
|
||||
"description": "Suggest core CLI equivalents for common commands"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"commands": {
|
||||
"status": {
|
||||
"description": "Show workspace and package status",
|
||||
"run": "core health"
|
||||
},
|
||||
"test": {
|
||||
"description": "Run tests in active package",
|
||||
"run": "core php test"
|
||||
},
|
||||
"lint": {
|
||||
"description": "Run linter in active package",
|
||||
"run": "core php lint"
|
||||
}
|
||||
},
|
||||
|
||||
"context": {
|
||||
"workspace_root": true,
|
||||
"registry_file": "repos.yaml",
|
||||
"packages_dir": "packages"
|
||||
}
|
||||
}
|
||||
70
.core/plugin/skills/package-status.md
Normal file
70
.core/plugin/skills/package-status.md
Normal file
|
|
@ -0,0 +1,70 @@
|
|||
# Package Status Skill
|
||||
|
||||
Show the status of all packages in the Host UK workspace.
|
||||
|
||||
## Quick Status
|
||||
|
||||
Run from workspace root:
|
||||
|
||||
```bash
|
||||
core health
|
||||
```
|
||||
|
||||
Output example:
|
||||
```
|
||||
18 repos │ 2 dirty │ 1 behind │ synced
|
||||
```
|
||||
|
||||
## Detailed Status
|
||||
|
||||
For a full status table:
|
||||
|
||||
```bash
|
||||
core work --status
|
||||
```
|
||||
|
||||
Output shows:
|
||||
- Package name
|
||||
- Git status (clean/dirty/staged)
|
||||
- Branch and tracking
|
||||
- Ahead/behind remote
|
||||
|
||||
## Check Specific Package
|
||||
|
||||
```bash
|
||||
cd packages/core-php
|
||||
git status
|
||||
```
|
||||
|
||||
Or check all dirty repos:
|
||||
|
||||
```bash
|
||||
core work --status | grep -v "clean"
|
||||
```
|
||||
|
||||
## Common Statuses
|
||||
|
||||
| Status | Meaning | Action |
|
||||
|--------|---------|--------|
|
||||
| `clean` | No changes | Ready to work |
|
||||
| `dirty` | Uncommitted changes | Commit with `core commit` |
|
||||
| `ahead` | Local commits to push | Push with `core push` |
|
||||
| `behind` | Remote has new commits | Pull with `core pull` |
|
||||
| `diverged` | Both ahead and behind | Manual merge needed |
|
||||
|
||||
## Workflow Commands
|
||||
|
||||
```bash
|
||||
core work # Full workflow: status → commit → push
|
||||
core commit # Commit dirty repos (Claude-assisted)
|
||||
core push # Push repos with unpushed commits
|
||||
core pull # Pull repos that are behind
|
||||
```
|
||||
|
||||
## GitHub Status
|
||||
|
||||
```bash
|
||||
core ci # GitHub Actions status
|
||||
core issues # Open issues across repos
|
||||
core reviews # PRs needing review
|
||||
```
|
||||
52
.core/plugin/skills/switch-package.md
Normal file
52
.core/plugin/skills/switch-package.md
Normal file
|
|
@ -0,0 +1,52 @@
|
|||
# Switch Package Skill
|
||||
|
||||
Switch the active package for the Host UK workspace.
|
||||
|
||||
## Usage
|
||||
|
||||
To switch the active package, edit `.core/workspace.yaml` and change the `active` field:
|
||||
|
||||
```yaml
|
||||
# .core/workspace.yaml
|
||||
active: core-tenant # Change this to the desired package
|
||||
```
|
||||
|
||||
## Available Packages
|
||||
|
||||
| Package | Type | Description |
|
||||
|---------|------|-------------|
|
||||
| `core-php` | foundation | Core PHP framework |
|
||||
| `core-tenant` | module | Multi-tenancy, workspaces |
|
||||
| `core-admin` | module | Admin panel, Livewire |
|
||||
| `core-api` | module | REST API, rate limiting |
|
||||
| `core-mcp` | module | MCP server framework |
|
||||
| `core-agentic` | module | AI agent orchestration |
|
||||
| `core-bio` | product | Link-in-bio pages |
|
||||
| `core-social` | product | Social media scheduling |
|
||||
| `core-analytics` | product | Privacy-first analytics |
|
||||
| `core-notify` | product | Push notifications |
|
||||
| `core-trust` | product | Social proof widgets |
|
||||
| `core-support` | product | Helpdesk, tickets |
|
||||
| `core-commerce` | module | Billing, Stripe |
|
||||
| `core-content` | module | CMS, pages, blog |
|
||||
| `core-tools` | module | Developer utilities |
|
||||
| `core-uptelligence` | module | Server monitoring |
|
||||
| `core-developer` | module | Developer portal |
|
||||
| `core-template` | template | Starter template |
|
||||
|
||||
## After Switching
|
||||
|
||||
After changing the active package:
|
||||
|
||||
1. Commands like `core php test` will target the new package
|
||||
2. Read the package's CLAUDE.md for specific guidance: `packages/{package}/CLAUDE.md`
|
||||
3. Install dependencies if needed: `cd packages/{package} && composer install`
|
||||
|
||||
## Quick Switch (CLI - Future)
|
||||
|
||||
Once `core workspace` commands are implemented:
|
||||
|
||||
```bash
|
||||
core workspace active core-tenant # Switch to core-tenant
|
||||
core workspace active # Show current active package
|
||||
```
|
||||
111
.core/plugin/skills/workspace.md
Normal file
111
.core/plugin/skills/workspace.md
Normal file
|
|
@ -0,0 +1,111 @@
|
|||
# Workspace Navigation Skill
|
||||
|
||||
You are working in the **Host UK developer workspace** - a federated monorepo containing 18 Laravel packages.
|
||||
|
||||
## Workspace Structure
|
||||
|
||||
```
|
||||
core-devops/ # You are here (workspace root)
|
||||
├── .core/
|
||||
│ ├── workspace.yaml # Active package config
|
||||
│ └── plugin/ # Claude Code integration
|
||||
├── packages/ # All packages cloned here
|
||||
│ ├── core-php/ # Foundation (no deps)
|
||||
│ ├── core-tenant/ # Multi-tenancy
|
||||
│ ├── core-admin/ # Admin panel
|
||||
│ ├── core-api/ # REST API
|
||||
│ ├── core-mcp/ # MCP server
|
||||
│ ├── core-agentic/ # AI agents
|
||||
│ ├── core-bio/ # Product: link-in-bio
|
||||
│ ├── core-social/ # Product: social scheduling
|
||||
│ ├── core-analytics/ # Product: analytics
|
||||
│ ├── core-notify/ # Product: push notifications
|
||||
│ ├── core-trust/ # Product: social proof
|
||||
│ ├── core-support/ # Product: helpdesk
|
||||
│ ├── core-commerce/ # Billing, Stripe
|
||||
│ ├── core-content/ # CMS
|
||||
│ ├── core-tools/ # Developer utilities
|
||||
│ ├── core-uptelligence/ # Server monitoring
|
||||
│ ├── core-developer/ # Developer portal
|
||||
│ └── core-template/ # Starter template
|
||||
└── repos.yaml # Package registry
|
||||
```
|
||||
|
||||
## Key Commands
|
||||
|
||||
### Workspace-level (run from root)
|
||||
```bash
|
||||
core health # Quick status: "18 repos │ clean │ synced"
|
||||
core work # Full workflow: status → commit → push
|
||||
core work --status # Status table only
|
||||
core commit # Claude-assisted commits for dirty repos
|
||||
core push # Push repos with unpushed commits
|
||||
core pull # Pull repos that are behind
|
||||
```
|
||||
|
||||
### Package-level (run from root, targets active package)
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
### GitHub integration
|
||||
```bash
|
||||
core issues # Open issues across repos
|
||||
core issues --assignee @me # Issues assigned to you
|
||||
core reviews # PRs needing review
|
||||
core ci # GitHub Actions status
|
||||
```
|
||||
|
||||
### Analysis
|
||||
```bash
|
||||
core impact core-php # Show what depends on core-php
|
||||
```
|
||||
|
||||
## Active Package
|
||||
|
||||
The **active package** is configured in `.core/workspace.yaml`. Commands like `core php test` run in the active package when executed from the workspace root.
|
||||
|
||||
To check or change the active package:
|
||||
```bash
|
||||
# Check current active package
|
||||
cat .core/workspace.yaml | grep "active:"
|
||||
|
||||
# Change active package (edit the file)
|
||||
# active: core-tenant
|
||||
```
|
||||
|
||||
## Package Types
|
||||
|
||||
Defined in `repos.yaml`:
|
||||
- **foundation**: `core-php` - base framework, zero dependencies
|
||||
- **module**: Infrastructure packages (tenant, admin, api, mcp, etc.)
|
||||
- **product**: User-facing apps (bio, social, analytics, etc.)
|
||||
- **template**: Starter for new projects
|
||||
- **meta**: This workspace repo (core-devops)
|
||||
|
||||
## Working in a Specific Package
|
||||
|
||||
When you need to work in a specific package:
|
||||
|
||||
1. **Navigate to it**: `cd packages/core-tenant`
|
||||
2. **Read its CLAUDE.md**: Each package has its own guidance
|
||||
3. **Run package commands**: `composer test`, `npm run dev`
|
||||
|
||||
Or from the workspace root, change the active package in `.core/workspace.yaml`.
|
||||
|
||||
## Dependencies
|
||||
|
||||
See `repos.yaml` for the full dependency tree. Key relationships:
|
||||
- `core-php` has no dependencies (foundation)
|
||||
- `core-tenant`, `core-admin`, `core-api`, `core-mcp` depend on `core-php`
|
||||
- Products depend on `core-php` and `core-tenant`
|
||||
- `core-agentic` depends on `core-php`, `core-tenant`, and `core-mcp`
|
||||
|
||||
## Tips
|
||||
|
||||
1. **Always prefer `core` commands** over raw git/composer when working across repos
|
||||
2. **Check `core health`** before starting work to see repo status
|
||||
3. **Use `core impact`** before changing shared packages
|
||||
4. **Each package has its own CLAUDE.md** with specific guidance
|
||||
24
.core/workspace.yaml
Normal file
24
.core/workspace.yaml
Normal file
|
|
@ -0,0 +1,24 @@
|
|||
# Host UK Workspace Configuration
|
||||
# This file configures the core CLI workspace behaviour
|
||||
version: 1
|
||||
|
||||
# Active package for `core php dev`, `core php test`, etc.
|
||||
# When running from the workspace root, commands target this package
|
||||
active: core-php
|
||||
|
||||
# Default package types for `core setup`
|
||||
# Only these types are cloned by default (override with --only flag)
|
||||
default_only:
|
||||
- foundation
|
||||
- module
|
||||
|
||||
# Paths
|
||||
packages_dir: ./packages
|
||||
|
||||
# Workspace-level settings
|
||||
settings:
|
||||
# Auto-suggest core commands when using raw git/composer
|
||||
suggest_core_commands: true
|
||||
|
||||
# Show package status in prompt (if shell integration enabled)
|
||||
show_active_in_prompt: true
|
||||
4
.gitignore
vendored
4
.gitignore
vendored
|
|
@ -2,8 +2,8 @@
|
|||
packages/*
|
||||
!packages/.gitkeep
|
||||
|
||||
# Core CLI cache (transient data)
|
||||
.core/
|
||||
# Core CLI cache (transient data, not config)
|
||||
.core/cache/
|
||||
|
||||
# IDE
|
||||
.idea/
|
||||
|
|
|
|||
135
CLAUDE.md
135
CLAUDE.md
|
|
@ -6,30 +6,75 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
|||
|
||||
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:
|
||||
|
||||
```yaml
|
||||
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
|
||||
|
||||
```bash
|
||||
# One-liner (macOS/Linux)
|
||||
# macOS/Linux
|
||||
git clone git@github.com:host-uk/core-devops.git && cd core-devops && make setup
|
||||
|
||||
# Or step by step
|
||||
make install-deps # Install go, gh, php, node, pnpm
|
||||
make install-core # Build/install core CLI to ~/.local/bin
|
||||
make clone # Clone all repos into packages/
|
||||
# Windows (PowerShell as Admin)
|
||||
.\scripts\install-deps.ps1 && .\scripts\install-core.ps1 && core setup
|
||||
```
|
||||
|
||||
Environment variables 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)
|
||||
```bash
|
||||
# Environment
|
||||
make setup # Full setup (deps + core + clone)
|
||||
core doctor # Check environment (requires: git, gh, php 8.3+, composer, node 20+, pnpm)
|
||||
# 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 (no 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
|
||||
|
|
@ -38,38 +83,66 @@ 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 with review status
|
||||
core reviews # List PRs needing review
|
||||
core ci # GitHub Actions workflow status
|
||||
|
||||
# Analysis
|
||||
# Dependency analysis
|
||||
core impact core-php # Show what depends on core-php
|
||||
```
|
||||
|
||||
## Working on Packages
|
||||
|
||||
### Active package (from root)
|
||||
```bash
|
||||
cd packages/core-php
|
||||
composer install
|
||||
composer test # Run Pest tests
|
||||
composer lint # Fix code style (Pint)
|
||||
npm run dev # Vite dev server (if has frontend)
|
||||
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
|
||||
```
|
||||
|
||||
## Package Types (repos.yaml)
|
||||
### Direct package work
|
||||
```bash
|
||||
cd packages/core-php
|
||||
composer install && composer test # Run Pest tests
|
||||
composer test -- --filter=ClassName # Single test
|
||||
./vendor/bin/pint --dirty # Format changed files
|
||||
```
|
||||
|
||||
| Type | Examples | Purpose |
|
||||
|------|----------|---------|
|
||||
| foundation | core-php | Base framework (no dependencies) |
|
||||
| module | core-tenant, core-admin, core-api, core-mcp | Infrastructure services |
|
||||
| product | core-bio, core-social, core-analytics | User-facing applications |
|
||||
| template | core-template | Starter for new projects |
|
||||
| meta | core-devops | This workspace repo |
|
||||
## Package Switching Workflow
|
||||
|
||||
## This Is a Workspace, Not Code
|
||||
To work on a different package without navigating:
|
||||
|
||||
Don't add code here. All actual development happens in `packages/core-*/`.
|
||||
1. Edit `.core/workspace.yaml`:
|
||||
```yaml
|
||||
active: core-tenant
|
||||
```
|
||||
|
||||
This repo manages:
|
||||
2. Run commands from workspace root:
|
||||
```bash
|
||||
core php test # Now runs in core-tenant
|
||||
```
|
||||
|
||||
3. Read the package's CLAUDE.md:
|
||||
```bash
|
||||
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`
|
||||
- **Clone failures** → `ssh -T git@github.com` to verify SSH keys
|
||||
|
||||
## This Repo's Scope
|
||||
|
||||
Don't add application code here. This repo only contains:
|
||||
- `repos.yaml` - Package registry with dependencies
|
||||
- `packages/` - Cloned repositories (git-ignored)
|
||||
- `scripts/` - Setup scripts for macOS/Linux/Windows
|
||||
- `scripts/` - Cross-platform setup scripts (install-deps, install-core)
|
||||
- `Makefile` - Setup orchestration
|
||||
- `.core/` - Workspace configuration and Claude Code integration
|
||||
|
|
|
|||
170
README.md
170
README.md
|
|
@ -1,96 +1,158 @@
|
|||
# Host UK Developer Workspace
|
||||
|
||||
This repository bootstraps a complete Host UK development environment.
|
||||
This repository is the **unified entry point** for Host UK development. One command sets up your entire environment.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### One-liner (macOS/Linux)
|
||||
```bash
|
||||
git clone git@github.com:host-uk/core-devops.git && cd core-devops && make setup
|
||||
```
|
||||
|
||||
### Step by step
|
||||
**Windows (PowerShell as Admin):**
|
||||
```powershell
|
||||
git clone git@github.com:host-uk/core-devops.git; cd core-devops; .\scripts\install-deps.ps1; .\scripts\install-core.ps1; core setup
|
||||
```
|
||||
|
||||
## What Happens
|
||||
|
||||
`make setup` does three things:
|
||||
|
||||
1. **Installs dependencies** - PHP 8.3+, Composer, Node 20+, pnpm, GitHub CLI
|
||||
2. **Installs the `core` CLI** - Multi-repo management tool
|
||||
3. **Clones all packages** - Into `packages/` (foundation and modules by default)
|
||||
|
||||
After setup, run `core doctor` to verify everything is working.
|
||||
|
||||
## What's Next
|
||||
|
||||
You're now ready to develop. The workspace starts with `core-php` as the active package.
|
||||
|
||||
```bash
|
||||
# 1. Clone this repo
|
||||
git clone git@github.com:host-uk/core-devops.git
|
||||
cd core-devops
|
||||
# Check your environment
|
||||
core doctor
|
||||
|
||||
# 2. Install dependencies and core CLI
|
||||
make setup
|
||||
# See workspace status
|
||||
core health
|
||||
|
||||
# Or manually:
|
||||
./scripts/install-deps.sh # Install go, gh, php, node, etc.
|
||||
./scripts/install-core.sh # Build and install core CLI
|
||||
# Run tests in the active package (core-php)
|
||||
core php test
|
||||
|
||||
# 3. Start developing
|
||||
# Switch to a different package
|
||||
# Edit .core/workspace.yaml and change "active: core-tenant"
|
||||
```
|
||||
|
||||
To work directly in a package:
|
||||
```bash
|
||||
cd packages/core-php
|
||||
composer install
|
||||
composer test
|
||||
```
|
||||
|
||||
### Windows (PowerShell as Admin)
|
||||
```powershell
|
||||
git clone git@github.com:host-uk/core-devops.git
|
||||
cd core-devops
|
||||
.\scripts\install-deps.ps1 # Install via Chocolatey
|
||||
.\scripts\install-core.ps1 # Build and install core CLI
|
||||
core setup # Clone all repos
|
||||
```
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Run `core doctor` to check your environment. You'll need:
|
||||
|
||||
- **Git** - Version control
|
||||
- **GitHub CLI** (`gh`) - For issues, PRs, CI status
|
||||
- **PHP 8.3+** - Laravel packages
|
||||
- **Composer** - PHP dependencies
|
||||
- **Node.js 20+** - Frontend builds
|
||||
- **pnpm** - Package manager (preferred over npm)
|
||||
|
||||
Optional but recommended:
|
||||
- **Claude Code** - AI-assisted development
|
||||
- **Docker** - For FrankenPHP runtime
|
||||
|
||||
## Commands
|
||||
|
||||
### Workspace-level
|
||||
```bash
|
||||
core setup # Clone all repos into packages/
|
||||
core setup --only foundation,module # Clone specific types
|
||||
core doctor # Check environment health
|
||||
core doctor --fix # Attempt to fix issues
|
||||
core health # Status summary: "18 repos │ clean │ synced"
|
||||
core work # Full workflow: status → commit → push
|
||||
core work --status # Status table only
|
||||
core commit # Claude-assisted commits for dirty repos
|
||||
core push # Push repos with unpushed commits
|
||||
core pull # Pull repos that are behind
|
||||
```
|
||||
|
||||
# Once set up, standard core commands work:
|
||||
core health # Status summary
|
||||
core work # Commit and push workflow
|
||||
core issues # View GitHub issues
|
||||
### Active package
|
||||
```bash
|
||||
core php test # Run Pest tests
|
||||
core php lint # Run Pint linter
|
||||
core php dev # Start Vite dev server
|
||||
```
|
||||
|
||||
### GitHub integration
|
||||
```bash
|
||||
core issues # Open issues across repos
|
||||
core issues --assignee @me
|
||||
core reviews # PRs needing review
|
||||
core ci # GitHub Actions status
|
||||
```
|
||||
|
||||
### Analysis
|
||||
```bash
|
||||
core impact core-php # Show what depends on core-php
|
||||
```
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
core-devops/
|
||||
├── .core/ # Workspace configuration
|
||||
│ ├── workspace.yaml # Active package, paths
|
||||
│ └── plugin/ # Claude Code integration
|
||||
├── packages/ # Cloned repositories (git-ignored)
|
||||
│ ├── core-php/
|
||||
│ ├── core-tenant/
|
||||
│ ├── core-php/ # Foundation framework
|
||||
│ ├── core-tenant/ # Multi-tenancy
|
||||
│ ├── core-admin/ # Admin panel
|
||||
│ └── ...
|
||||
├── repos.yaml # Package registry
|
||||
└── README.md
|
||||
└── repos.yaml # Package registry
|
||||
```
|
||||
|
||||
## Updating
|
||||
## Prerequisites
|
||||
|
||||
Run `core doctor` to check your environment. Required:
|
||||
|
||||
- **Git** - Version control
|
||||
- **GitHub CLI** (`gh`) - Issues, PRs, CI status
|
||||
- **PHP 8.3+** - Laravel packages
|
||||
- **Composer** - PHP dependencies
|
||||
- **Node.js 20+** - Frontend builds
|
||||
- **pnpm** - Package manager
|
||||
|
||||
Optional:
|
||||
- **Claude Code** - AI-assisted development
|
||||
- **Docker** - For FrankenPHP runtime
|
||||
|
||||
## Package Types
|
||||
|
||||
Defined in `repos.yaml`:
|
||||
|
||||
| Type | Packages | Description |
|
||||
|----------------|------------------------------------------------------------|---------------------------------|
|
||||
| **foundation** | `core-php` | Base framework, zero dependencies |
|
||||
| **module** | `core-tenant`, `core-admin`, `core-api`, `core-mcp`, etc. | Infrastructure |
|
||||
| **product** | `core-bio`, `core-social`, `core-analytics`, etc. | User-facing apps |
|
||||
| **template** | `core-template` | Starter for new projects |
|
||||
| **meta** | `core-devops` | This workspace repo |
|
||||
|
||||
By default, `core setup` clones foundation and module packages. To clone specific types:
|
||||
```bash
|
||||
core pull # Pull updates for all repos
|
||||
core pull --all # Pull even if not behind
|
||||
core setup --only foundation,module,product
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**"core: command not found"**
|
||||
Install the Core CLI from https://github.com/Snider/Core
|
||||
```bash
|
||||
make install-core
|
||||
```
|
||||
|
||||
**"gh: command not found"**
|
||||
Install GitHub CLI: `brew install gh` then `gh auth login`
|
||||
```bash
|
||||
brew install gh && gh auth login
|
||||
```
|
||||
|
||||
**Clone failures**
|
||||
Check your SSH keys: `ssh -T git@github.com`
|
||||
```bash
|
||||
ssh -T git@github.com # Verify SSH keys
|
||||
```
|
||||
|
||||
**Missing dependencies**
|
||||
```bash
|
||||
core doctor --fix
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
- **This repo's CLAUDE.md** - Guidance for Claude Code in the workspace
|
||||
- **repos.yaml** - Full package registry with dependencies
|
||||
- **`.core/docs/core-folder-spec.md`** - Specification for `.core/` folders
|
||||
|
||||
Each package in `packages/` has its own CLAUDE.md with package-specific guidance.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue