create-gl-life-claude

Scaffold new projects with the GL.Life Claude Code enforcement framework

A project generator that sets up a structured development environment with Claude Code integration, task tracking, and automated workflow enforcement.

Features

• Interactive CLI - Guided project setup with prompts
• Structured Development - Enforced task-based workflow with plan tracking
• UI Verification System - Automated validation: syntax, runtime, visual, contracts
• Port Management - Fixed port allocation with auto-cleanup (3000-3009 range)
• Component Contracts - Define and enforce component specifications
• Protected Scripts - Minified, bundled scripts and hooks (27% smaller than source)
• Git Integration - Automatic repository initialization with structured commits
• Hook System - Pre/post tool-use hooks for code quality and workflow enforcement
• Integration Test Site - Hot-reloading site for stakeholder validation
• Zero Configuration - Works out of the box with sensible defaults

Installation

NPX (Recommended - No Installation Required)

npx gl-life-claude-zen my-project

Global Installation

npm install -g gl-life-claude-zen
gl-life-claude-zen my-project

Usage

Quick Start

# Interactive mode (prompts for options)
npx gl-life-claude-zen

# Direct mode (uses defaults)
npx gl-life-claude-zen my-project

Interactive Options

When run without arguments, the CLI prompts for:

• Project name (lowercase, numbers, hyphens, underscores)
• Git initialization (creates repo with initial commit)
• Dependency installation (runs npm install)

What Gets Created

my-project/
├── .claude/
│   ├── settings.json          # Claude Code configuration
│   ├── CLAUDE.md               # Development guidelines
│   ├── ONBOARDING.md           # 🎯 READ THIS FIRST - Critical instructions
│   ├── POST-INSTALL.md         # Step-by-step setup for Claude
│   ├── PLAN-SCHEMA.json        # Plan structure definition
│   └── PROJECT-PLAN-TEMPLATE.json
├── Agent/                      # ✅ Your workspace (EDIT HERE)
│   ├── src/                    # Source code
│   ├── tests/                  # Test files
│   └── db/                     # Database scripts
├── scripts/                    # ✅ Your scripts (EDIT HERE)
├── test-site/                  # Integration testing site
├── node_modules/
│   └── .gl-life-claude/
│       ├── scripts/            # 17 bundled workflow scripts
│       └── hooks/              # 29 bundled enforcement hooks
├── .git/hooks/                 # Git hooks (auto-installed)
├── package.json                # With workflow scripts configured
├── README.md                   # Project documentation
└── .gitignore                  # Standard ignores

Available Commands

Once your project is created, navigate into it and use these commands:

Planning

npm run plan:generate    # Generate plan from requirements (AI-assisted)
npm run plan:create      # Create new project plan manually
npm run plan:init        # Initialize plan and lock it
npm run plan:manager     # Manage and switch between plans
npm run plan:amend       # Amend locked plan (creates audit trail)
npm run plan:help        # Show planning command help

Task Management

npm run task:start TASK-001  # Start a specific task
npm run task:next            # Auto-start next available task
npm run task:done TASK-001   # Complete current task
npm run task:status          # View project progress

Plan Management

npm run plan:activate PLAN-001  # Set active plan
npm run plan:manager            # Interactive plan manager

Utilities

npm run help             # Show all available commands

Workflow

1. Generate a Plan (Recommended)

Option A: AI-Assisted (Recommended)

# Interactive mode - describe your project
npm run plan:generate

# One-liner
npm run plan:generate "Build a task management app with React and Node.js"

# From file
npm run plan:generate -- --from-file ./requirements.txt

This creates a PROJECT-REQUIREMENTS.txt file. Then ask Claude:

"Please read .claude/plans/plan-001-generated/PROJECT-REQUIREMENTS.txt
and create a detailed project plan"

Claude will analyze your requirements and create a comprehensive PROJECT-PLAN.json with:

• Hierarchical organization - Projects → Subprojects → Milestones → Tasks
• Dependency tracking - Tasks can depend on other tasks
• Phase organization - Design, implementation, testing, deployment
• Time estimation - Realistic hours per task

Option B: Manual Creation

npm run plan:create

Manually create the plan JSON structure.

2. Initialize & Lock

npm run plan:init

Locks the plan and generates:

• TASK-TRACKER.json - Real-time progress tracking
• Individual task files (TASK-001.json, etc.)
• Immutable plan structure (changes require amendments)

3. Work on Tasks

npm run task:next        # Starts next available task
# ... make changes ...
git commit -m "[TASK-001] Implemented feature"
npm run task:done TASK-001

4. Track Progress

npm run task:status

Shows:

• Overall progress percentage
• Completed, in-progress, pending, blocked tasks
• Time estimates vs actual time spent
• Next available tasks

Hook System

The framework includes enforcement hooks that run automatically:

Pre-Tool-Use Hooks

• validate-git-workflow - Enforces branch naming, commit messages
• validate-task-completion - Ensures active task exists before code changes

Post-Tool-Use Hooks

• enforce-structured-development - Blocks modifications without active task
• auto-format - Formats code automatically
• validate-test-quality - Ensures tests have real assertions
• validate-ui-integration - Requires UI component tests
• validate-database-changes - Validates migration workflow
• validate-test-results - Blocks commits if tests fail
• enforce-test-pyramid - Ensures balanced test coverage
• enforce-migration-workflow - Protects immutable migrations

Configuration

settings.json

Configure Claude Code behavior:

{
  "permissions": {
    "allow": ["Read(**)", "Glob", "Grep", "Bash(npm run *)"],
    "ask": ["Edit(./package.json)"],
    "deny": ["Edit(**/*.md)", "Bash(rm -rf*)"]
  },
  "testing": {
    "ui": {
      "strictMode": true,
      "requireTestFile": true,
      "requireImport": true,
      "requireRender": true,
      "requireProps": true,
      "requireEventTests": true,
      "requireApiMocking": true,
      "requireStateTests": true,
      "requireFormTests": true,
      "requireConditionalTests": true,
      "requireIntegrationSite": true,
      "integrationSiteDir": "test-site",
      "conditionalThreshold": 3
    }
  },
  "hooks": {
    "PreToolUse": [...],
    "PostToolUse": [...]
  }
}

UI Verification System

The framework includes automated UI component validation with four validation stages:

1. Syntax Validation - TypeScript/JSX compilation and import resolution
2. Runtime Validation - Browser-based runtime error detection (requires Playwright)
3. Visual Validation - AI-powered visual appearance analysis (requires Claude Vision API)
4. Contract Validation - Component contract compliance checking

Quick Configuration:

{
  "testing": {
    "ui": {
      "strictMode": true,
      "requireVisualCheck": true,
      "requireContract": false
    }
  }
}

Documentation:

• UI Verification Guide - Complete validation system guide
• Port Management - Fixed port allocation and auto-cleanup
• Component Contracts - Contract schema reference
• CHANGELOG - Version history and breaking changes

UI Testing Configuration

The framework enforces strict UI testing requirements by default. Configure these in .claude/settings.json:

Global Strict Mode

{
  "testing": {
    "ui": {
      "strictMode": true  // false = warnings only, true = blocks commits
    }
  }
}

Per-Requirement Controls

{
  "testing": {
    "ui": {
      "strictMode": true,
      "requireProps": true,           // Tests must provide required props
      "requireEventTests": true,      // Tests must simulate user events
      "requireApiMocking": true,      // Tests must mock API calls
      "requireStateTests": true,      // Tests must validate state changes
      "requireFormTests": true,       // Tests must validate form submission
      "requireConditionalTests": true,// Tests must cover conditional branches
      "requireIntegrationSite": true  // Components must be in test-site/
    }
  }
}

UI Testing Requirements (Hard Requirements - Always Enforced)

All UI testing requirements are hard requirements that always block commits if violated:

• requireTestFile - UI component must have test file
• requireImport - Test must import the component
• requireRender - Test must render the component
• requireProps - Tests must provide required props (validates prop passing)
• requireEventTests - Tests must simulate user events (validates user interactions)
• requireApiMocking - Tests must mock API calls (validates async behavior)
• requireStateTests - Tests must validate state changes (validates state management)
• requireFormTests - Tests must validate form submission (validates form behavior)
• requireConditionalTests - Tests must cover conditional branches (validates logic paths)
• requireIntegrationSite - Components must be in test-site/ (validates stakeholder preview)

Important Notes:

• ⚠️ These requirements CANNOT be disabled - They always enforce strict UI testing standards
• 🚫 Commits will be blocked if any requirement is violated
• ✅ Zero compromise on quality - All UI components must have comprehensive tests
• 🎯 Best practice enforcement - Ensures production-ready components

Configuration (for reference only):

{
  "testing": {
    "ui": {
      "strictMode": true,              // Always true (hard requirement)
      "requireTestFile": true,         // Cannot disable
      "requireImport": true,           // Cannot disable
      "requireRender": true,           // Cannot disable
      "requireProps": true,            // Cannot disable
      "requireEventTests": true,       // Cannot disable
      "requireApiMocking": true,       // Cannot disable
      "requireStateTests": true,       // Cannot disable
      "requireFormTests": true,        // Cannot disable
      "requireConditionalTests": true, // Cannot disable
      "requireIntegrationSite": true   // Cannot disable
    }
  }
}

Why Hard Requirements?

This framework enforces production-grade quality standards:

• No shortcuts - Every UI component gets proper test coverage
• Stakeholder confidence - Integration site ensures visual validation
• Maintainability - Comprehensive tests prevent regressions
• Professional standards - Enforces industry best practices

Integration Test Website

UI components must be added to the test-site/ directory for stakeholder validation:

cd test-site
npm install
npm run dev  # Runs at http://localhost:3000

Deploy to stakeholders:

cd test-site
npm run deploy  # Deploys to GitHub Pages

Configuration:

{
  "testing": {
    "ui": {
      "requireIntegrationSite": true,
      "integrationSiteDir": "test-site"  // Or custom directory
    }
  }
}

See test-site/README.md for full integration testing guide.

CLAUDE.md

Project-specific development guidelines and rules. Customize for your team's workflow.

Examples

Create a new web application with AI-generated plan

npx gl-life-claude-zen my-web-app
cd my-web-app

# Generate plan from requirements
npm run plan:generate "Build a task management web application with:
- User authentication (email/password)
- Task CRUD operations
- Task categories and tags
- Priority levels and due dates
- Search and filtering
- React frontend with TypeScript
- Node.js/Express backend
- PostgreSQL database"

# Ask Claude to create the plan
# In Claude Code: "Please read the PROJECT-REQUIREMENTS.txt and create a project plan"

# Lock the plan
npm run plan:init

# Start working
npm run task:next

Resume existing project

cd my-project
npm run task:status    # See where you left off
npm run task:next      # Continue with next task

Requirements

• Node.js >= 18.0.0
• npm, yarn, or pnpm
• Git (optional, for git integration)

Bundle Protection

Scripts and hooks are:

• Minified - 27% smaller than source
• Bundled - All dependencies inlined
• Executable - Shebang preserved for direct execution
• Protected - Harder to accidentally modify

License

APACHE 2.0

Support

email: [email protected] website: www.gl.life