Installation & Setup

GigiKit scaffolds a structured .claude/ directory into your project, giving Claude Code the rules, skills, and agent configurations it needs to orchestrate complex development workflows.

Prerequisites

Before installing, confirm these are available on your system:

• Node.js 18+ — required for the gk CLI and skill scripts
• Claude Code CLI — the underlying agent runtime GigiKit extends
• Git — recommended for worktree-based parallel agent execution

Install the CLI

GigiKit CLI (@gpp/gigikit-cli) is published on a private Verdaccio registry. Kits are bundled inside the CLI package — no separate download or GitLab token required.

Step 1: Fix npm global permissions (one time)

By default, npm install -g may require sudo on macOS/Linux. Run this once to fix:

After this, all npm install -g commands work without sudo.

Step 2: Login to registry (first time only)

npm login --registry=https://registry-aawp.vnggames.net/

Step 3: Install CLI

# macOS / Linux
npm config set "@gpp:registry" https://registry-aawp.vnggames.net/
npm install -g @gpp/gigikit-cli

# Windows (PowerShell) — quotes required to avoid shell parsing errors
npm config set "@gpp:registry" https://registry-aawp.vnggames.net/
npm install -g "@gpp/gigikit-cli"

This gives you the gk command.

Update to latest CLI version

# macOS / Linux
npm update -g @gpp/gigikit-cli

# Windows (PowerShell)
npm update -g "@gpp/gigikit-cli"

Create or Initialize a Project

New project

gk new my-project --kit engineer

Existing project

cd /path/to/existing-project
gk init --kit engineer

CLI Options

The command scaffolds the following structure:

your-project/
├── CLAUDE.md              # Orchestrator instructions for Claude Code
├── AGENTS.md              # Instructions for OpenCode agents
└── .claude/
    ├── rules/
    │   ├── primary-workflow.md
    │   ├── development-rules.md
    │   ├── orchestration-protocol.md
    │   └── documentation-management.md
    ├── hooks/
    │   └── ...              # Lifecycle hooks for agent behavior
    ├── skills/
    │   ├── cook/
    │   ├── plan/
    │   ├── test/
    │   └── code-review/
    ├── agents/
    │   └── ...              # Agent definitions
    ├── scripts/
    │   └── set-active-plan.cjs
    └── metadata.json        # Kit name and version tracking

Update Kit Files

Keep your kit up to date. The update command auto-detects your installed kit from .claude/metadata.json:

gk update
# or explicitly
gk update --kit engineer

Use local kit (for development)

gk new my-project --kit engineer --local /path/to/gigikit-engineer
gk init --kit marketing --local /path/to/gigikit-marketing

Key Configuration Files

CLAUDE.md

This is the primary instruction file Claude Code reads at session start. It defines the agent’s role, points to workflow rules, and sets global constraints. A minimal CLAUDE.md looks like:

# CLAUDE.md

## Role & Responsibilities
Analyze requirements, delegate to sub-agents, ensure quality delivery.

## Workflows
- Primary workflow: `./.claude/rules/primary-workflow.md`
- Development rules: `./.claude/rules/development-rules.md`
- Orchestration: `./.claude/rules/orchestration-protocol.md`

AGENTS.md

Used by OpenCode agents. Mirrors CLAUDE.md structure but targets the OpenCode runtime. Both files should stay in sync when you update workflows.

Install Skill Dependencies

Some skills require external tools (FFmpeg, ImageMagick, Python packages). Run the automated installer:

cd .claude/skills
chmod +x install.sh
./install.sh

The installer supports these flags:

Verification Steps

After setup, verify GigiKit is wired correctly:

# 1. Confirm structure exists
ls .claude/rules/
ls .claude/skills/

# 2. Open Claude Code in your project
claude

# 3. Test skill activation
/gk:cook "say hello"

If Claude responds by activating the cook skill workflow, installation succeeded.

After Installation

# Start Claude Code in your project
claude

# Use GigiKit skills (prefix: gk:)
/gk:plan "implement user authentication"
/gk:cook "add database integration"
/gk:fix "resolve login bug"

Next Steps

With GigiKit installed, follow the Quick Start guide to run your first end-to-end feature using the /gk:cook skill.