majiayu000/profile-control-plane compiles YAML into self-hosted GitHub profile READMEs

Compile a GitHub identity into an animated, dark/light, self-hosted profile README.

Most profile generators render a banner or assemble remote widgets. Profile Control Plane turns your repositories into a coherent visual system: a hero, a project map, flagship work, and an expandable module registry—all generated from one reviewed YAML file and one of sixteen distinct templates.

What you get

• One declarative profile.yaml as the authoring source of truth.
• Sixteen templates, each producing four SVGs with native dark/light variants and reduced-motion support.
• A generated GitHub-safe README.md with escaped metadata and optional star badges.
• init, build, preview, and check commands with typed, fail-closed errors.
• A bundled design-github-profile agent skill for evidence-backed positioning, profile archetype selection, visual review, and safe staging.
• No hosted image API, database, analytics, or required token at render time.

Template gallery

Every preview below is generated from the same examples/lifcc/profile.yaml. GitHub selects the matching dark or light asset automatically.

Control Plane

The default Control Plane hero is shown at the top of this README.

View the closed-loop architecture map

Command Deck (command-deck)

View the execution deck

Signal Grid (signal-grid)

View the signal topology

Editorial

View the working index

Developer Workbench (bento-grid)

View the connected build map

Terminal

View the process tree

Blueprint

View the assembly drawing

Constellation

View the star chart

Metro Map (metro)

View the network map

Monolith (monolith)

monolith-output/assets/hero-dark.svg">

View the typographic route

Interlace (interlace)

View the project weave

Cipher Print (cipher-print)

View the engraved index

Field Specimen (field-specimen)

View the classification plate

Patch Bay (patchbay)

View the cable routing

Cartograph (cartograph)

View the contour survey

Foundry (foundry)

View the casting floor

Quick start

The package is currently distributed from GitHub. Build and link the CLI locally:

git clone https://github.com/majiayu000/profile-control-plane.git
cd profile-control-plane
npm ci
npm link

Create a starter configuration from public GitHub metadata:

profilectl init YOUR_GITHUB_USERNAME
profilectl check
profilectl preview --all-templates

Open the printed comparison page, choose a direction, set theme.preset, and refine profile.yaml until it tells the right story. Then build:

profilectl build --out .profile-output

If the unauthenticated GitHub API is rate-limited, provide an existing token only for init:

GITHUB_TOKEN=your_token profilectl init YOUR_GITHUB_USERNAME

The token is read from the environment and is never written to the configuration or generated assets.

Configuration

version: 1
github:
  username: octocat
identity:
  name: Octocat
  headline: AGENT INFRASTRUCTURE
  tagline: Building the systems around coding agents.
theme:
  preset: control-plane
  primary: "#00A7D1"
  secondary: "#E84A8A"
layers:
  - name: DIRECT
    project: agent-cli
    description: The primary execution surface
    tone: primary
flagships:
  - repo: agent-cli
    role: EXECUTE
    description: A fast, inspectable coding agent.
    tone: primary
module_groups: []
settings:
  show_stars: true
  show_badges: true

The complete contract is schemas/profile.schema.json. The starter importer uses factual GitHub names, descriptions, languages, stars, and timestamps. It deliberately emits generic SYSTEM 01 / PROJECT 01 labels because semantic architecture should be reviewed, not hallucinated.

See the curated lifcc configuration and its generated output.

Templates

The bundled agent skill can recommend a preset from repository evidence. The user remains the decision maker: profilectl preview --all-templates renders the same configuration in all sixteen directions before anything is built or staged.

Commands

Use --help on any command for options. build --force refuses to replace the current directory, a filesystem root, or any directory containing .git.

Publish safely

Generated output is intentionally separate from your profile repository. On a new branch in the USERNAME/USERNAME repository, copy only these files:

.profile-output/README.md  -> README.md
.profile-output/assets/    -> assets/

Review the rendered branch and diff before merging. The CLI never commits, pushes, changes pins, or merges to main.

Agent skill

Copy the bundled skill into your agent skill directory, or reference it from this repository:

cp -R skills/design-github-profile ~/.codex/skills/

Then ask: Use $design-github-profile to redesign my GitHub profile. The skill audits existing profile files, separates verified facts from interpretations and user intent, proposes an evidence-backed profile direction, and evaluates the rendered result before preparing a preview branch. Detailed archetypes, visual guidelines, and the publication rubric load only when the task needs them.

The agent recommends a narrative and a supported preset, explains its evidence, and can render all templates for user choice. If the desired visual direction is outside the declared presets, it reports the capability gap instead of inventing a theme.preset or forcing the account into an unsupported metaphor.

Design and safety

The compiler is pure: validated config goes in; static strings come out. Network and filesystem behavior live in explicit adapters. SVG output is XML-validated and rejected if it contains script elements, event attributes, or JavaScript URLs. Files are staged before an atomic directory replacement.

Read the architecture foundation, security policy, and contribution guide for details.

Development

npm ci
npm run check
npm pack --dry-run

The test gate requires at least 80% line, statement, function, and branch coverage.