bluegroup_core_foundation

The shared foundation for our projects — the one place our development guardrails live, so every other project points here instead of repeating the rules per repo.

Each project is its own standalone repo and points at this foundation for shared CI guardrails, permissions, and skills. Only the process is shared — not the design, with one exception: WordPress plugin admin screens, which all come from the shared blueworx-admin-design system committed here at .claude/skills/blueworx-admin-design/. That system also carries the page editor — the shared shell and behaviour for any screen where a site owner edits a record or plugin settings, so every plugin's editing experience is the same one. Page content is edited in WordPress's block editor, not on a screen of ours.

Starter Prompt

New projects are set up by pasting the matching Starter Prompt (standalone / WordPress plugin / headless) into Claude Code — there are no starter template repos to clone from.

As part of that setup, every new project copies CLAUDE.md.template into its own repo root as CLAUDE.md. This carries the condensed global rules into the project itself, so the guardrails stay consistent regardless of whose machine the project is opened on — rather than relying on each person's personal ~/.claude/CLAUDE.md.

# from a new project's repo root
curl -o CLAUDE.md \
  https://raw.githubusercontent.com/blueworx-io/bluegroup_core_foundation/main/CLAUDE.md.template

All three are saved here, and each is self-contained — paste the matching one into Claude Code in the new, empty repo and the result passes its CI workflow on the first pull request:

• docs/starter-prompt-standalone.md
• docs/starter-prompt-wordpress-plugin.md
• headless — the initial setup, then the framework prompt below

For headless projects there is a saved follow-on prompt, docs/starter-prompt-headless-framework.md, that scaffolds the standard framework — Next.js (App Router) + TypeScript — on top of the initial setup.

Skills note: the approved skills load automatically from the shared Claude Code settings, with one exception — graphify is a per-machine Python CLI. Install it once per machine with uv tool install graphifyy && graphify install. The CLI installs to ~/.local/bin (Windows: %USERPROFILE%\.local\bin), which may not be on PATH — if graphify isn't found, add that directory to PATH rather than reinstalling. The template's Skill Usage Policy section then tells Claude Code when and how to fire each skill automatically, so nobody has to remember to invoke them.

Using the CI guardrails

Instead of repeating the rules per repo, a project adds one small caller workflow that points at the reusable workflow for its type. On every pull request the shared workflow installs + lints, builds, checks the version bump, checks the changelog, checks dependencies against the project's approved-deps.json, checks a WordPress plugin's copy of the shared admin design system is current, runs PHPCS and PHPUnit when their configs are present, and runs Playwright.

Standalone

# .github/workflows/ci.yml
name: CI
on: pull_request
jobs:
  guardrails:
    uses: blueworx-io/bluegroup_core_foundation/.github/workflows/ci-standalone.yml@v1
    with:
      foundation_ref: v1

Headless

name: CI
on: pull_request
jobs:
  guardrails:
    uses: blueworx-io/bluegroup_core_foundation/.github/workflows/ci-headless.yml@v1
    with:
      foundation_ref: v1

The Netlify deploy preview is a required check on headless projects, and it is the only thing that makes headless different from standalone. The workflow waits for Netlify's deploy-preview commit status on the PR head, fails if it failed or never arrived, then fails again if the preview URL doesn't answer — a green status on a site that 404s behind deploy protection is not a preview anyone can review. Connect the repo to Netlify, or set require_netlify_preview: false and say in the caller workflow why this project has no preview.

WordPress plugin (Playwright runs against a disposable WordPress the run provisions itself — PHP + SQLite, no Docker, no hosting):

name: CI
on: pull_request
jobs:
  guardrails:
    uses: blueworx-io/bluegroup_core_foundation/.github/workflows/ci-wordpress.yml@v1
    with:
      plugin_slug: my-plugin
      use_local_wordpress: true
      foundation_ref: v1
    secrets: inherit

This is the default for new plugin projects. See docs/wordpress-test-harness.md for how to run the same instance locally, and add .wp-test/ to the project's .gitignore.

The alternative — preview_url: https://staging.example.com against a hosted staging site — is still supported, but it is how CI came to report green while running zero tests: a placeholder URL makes every spec skip itself. If you use it, point it at something real and pass WP_ADMIN_USER / WP_ADMIN_PASS.

secrets: inherit is not optional in practice. Tests that sign in to wp-admin need WP_ADMIN_USER and WP_ADMIN_PASS as repo secrets. Without them those specs skip themselves and the run reports green having asserted nothing. Pass them explicitly instead if you prefer:

    secrets:
      WP_ADMIN_USER: ${{ secrets.WP_ADMIN_USER }}
      WP_ADMIN_PASS: ${{ secrets.WP_ADMIN_PASS }}

The same trap applies to preview_url: point it at a real instance. Specs that guard on a placeholder URL skip too.

This is the beginning of the README. Read the rest at the original. Read the full README ↗