Welcome Experience Customization

Welcome Experience Customization

One-pass orchestrated customization of the entire Alex welcome experience — loop menu, taglines, identity, North Star, and persona.

Unifies what was previously fragmented across 4 separate skills (sidebar-customization, project-taglines, identity-customization, north-star) into a single guided workflow that detects project context and generates all config files coherently.

When to Use

• New heir project initialization (after alex.initialize)
• Rebranding or pivoting an existing project
• During meditation when customization surfaces as a consolidation target
• When the sidebar feels generic and doesn't reflect the project's domain
• When switching project phases (planning → active-development → release)

Quick Reference

Automatic Systems (no config needed)

Orchestrated Customization Workflow

Step 1: Detect Project Context

Read these sources to understand the project:

Step 2: Classify Project Type

Step 3: Generate Config Files

Generate all files in sequence, ensuring cross-references are consistent:

3a. North Star (.github/NORTH-STAR.md)

# North Star: [Project Name]

> [One-sentence ambitious vision]

## What This Means

[2-3 sentences expanding the vision into concrete outcomes]

## Guiding Principles

1. [Principle derived from project domain]
2. [Principle derived from team values]
3. [Principle derived from user needs]

3b. Identity (copilot-instructions.md)

Update the identity layer only (preserve Safety + Routing sections):

## Identity

[First-person domain voice, 1-3 sentences]

## Active Context

Persona: [detected or chosen persona]
Objective: [from North Star]
Tone: [project-appropriate: Direct/Friendly/Formal/Technical]
Focus: [comma-separated domain keywords]
Principles: KISS, DRY, Quality-First
North Star: [vision one-liner from NORTH-STAR.md]

3c. Taglines (taglines.json)

{
  "version": "1.0",
  "project": "[Project Name]",
  "taglines": {
    "project": ["[8-12 identity taglines, 5-60 chars each]"],
    "vision": ["[4-6 North Star-derived taglines]"],
    "collaboration": ["[4-6 partnership taglines]"]
  },
  "rotation": {
    "strategy": "balanced",
    "projectWeight": 50,
    "inspirationalWeight": 50
  }
}

Tagline quality rules:

• 5-60 characters per tagline
• No generic filler ("We do great things")
• Each tagline should be recognizable as this project
• Vision taglines derive from North Star document
• Collaboration taglines reflect the team dynamic

3d. Loop Menu (loop-menu.json)

{
  "$schema": "../../../heir/.github/config/loop-config.schema.json",
  "version": "1.0",
  "projectType": "[detected type]",
  "projectPhase": "[current phase]",
  "groups": [
    {
      "id": "creative-loop",
      "label": "[Project] Creative Loop",
      "icon": "lightbulb",
      "collapsed": false,
      "buttons": ["[phase-appropriate workflow buttons]"]
    },
    {
      "id": "[domain]-helpers",
      "label": "[DOMAIN] HELPERS",
      "icon": "[domain-icon]",
      "collapsed": true,
      "buttons": ["[domain-specific quick actions]"]
    }
  ]
}

Loop menu rules:

• Creative loop group always first (Ideate → Plan → Build → Test → Release → Improve)
• Domain helpers second, collapsed by default
• Use phase arrays to show/hide buttons per project phase
• Use promptFile for prompts longer than one sentence
• Max 6 buttons per group for scannability

Step 4: Validate Coherence

Cross-check all generated files:

Project-Type Templates

Web App Template

Loop groups: Creative Loop, UI/UX, Components, Testing, Deploy Taglines: "Pixel-perfect experiences", "Components that compose", "Ship with confidence" Persona: Developer or Frontend Phase default: active-development

API/Backend Template

Loop groups: Creative Loop, API Design, Data Layer, Testing, Deploy Taglines: "APIs developers love", "Contracts before code", "Reliable at scale" Persona: Developer or Architect Phase default: active-development

Data Pipeline Template

Loop groups: Creative Loop, Ingest, Transform, Quality, Publish Taglines: "Data you can trust", "From raw to refined", "Insights at scale" Persona: Data-Engineer Phase default: active-development

Infrastructure Template

Loop groups: Creative Loop, Provision, Configure, Monitor, Govern Taglines: "Infrastructure as intention", "Repeatable by design", "Cloud-native governance" Persona: DevOps or Architect Phase default: planning

Research Template

Loop groups: Creative Loop, Literature, Method, Analysis, Writing Taglines: "Evidence before opinion", "Rigor meets curiosity", "Discovery through method" Persona: Researcher or Academic Phase default: planning

Skill Partial Authoring

Skills can inject buttons into the Loop tab via loop-config.partial.json:

// .github/skills/my-skill/loop-config.partial.json
{
  "group": "domain-helpers",
  "buttons": [
    {
      "icon": "beaker",
      "label": "Run My Skill",
      "command": "openChat",
      "prompt": "Use the my-skill workflow to..."
    }
  ]
}

Partials are merged into the Loop tab at load time by loopMenu.ts.

Phase Lifecycle

Update projectPhase in loop-menu.json as the project evolves:

Integration with Meditation

During meditation sessions, the welcome experience is a natural consolidation target:

1. Review: What workflows did I actually use? (check frecency data)
2. Relate: Do the taglines still reflect where the project is?
3. Reinforce: Should any loop menu groups be added/removed/reordered?
4. Record: Update configs to match current project reality

Meditation prompt addition:

"Review the welcome experience — are the loop menu, taglines, and identity still aligned with the project's current phase and direction? Update any that have drifted."

Anti-Patterns

Checklist

• Project context detected (type, stack, phase)
• North Star created or updated
• Identity layer customized (persona, tone, North Star reference)
• Taglines generated (8-12 project, 4-6 vision, 4-6 collaboration)
• Loop menu configured (creative loop + domain helpers)
• Phase set correctly in loop-menu.json
• Cross-reference validation passed
• All configs committed to .github/config/