Starting a New Project

Initialize MeowKit and scaffold your first plan.

Best for: First-time users
Time estimate: 5 minutes
Skills used: create-meowkit CLI, meow:plan-creator

Overview

This workflow gets you from an empty project to a fully configured MeowKit environment with your first approved plan. By the end, you'll understand how MeowKit's agents, gates, and workflow phases work together.

Prerequisites

• Node.js 20+, Python 3.9+, Git installed
• Claude Code installed (claude.ai/code)
• A project directory (new or existing)

Step-by-step guide

Step 1: Install MeowKit

npm create meowkit@latest

The CLI auto-detects your tech stack and asks configuration questions (project name, stack, team size, mode, memory, optional Gemini API key). Takes ~30 seconds.

What gets created: A .claude/ directory with 13 agents, 42 skills, lifecycle hooks, security rules, and a memory system. Plus CLAUDE.md (the entry point Claude reads at session start).

Step 2: Verify installation

npx meowkit doctor

Checks: Node.js version, Python available, Git configured, hooks executable, scripts present.

Step 3: Start Claude Code

claude

Claude reads CLAUDE.md automatically. The orchestrator agent activates and reads memory/lessons.md (empty on first run) and memory/cost-log.json.

Step 4: Plan your first feature

/meow:plan add user authentication with JWT

Here's what happens behind the scenes:

1. Orchestrator classifies the task as COMPLEX (auth-related → always complex) and assigns the Opus model tier
2. Orchestrator routes to the planner agent
3. Planner applies two lenses:
   • Product lens: "Is JWT the right choice? Have you considered session-based auth? What are your scale requirements?"
   • Engineering lens: "Where will tokens be stored? What's the refresh strategy? How will you handle token revocation?"
4. Planner produces a plan file at tasks/plans/YYMMDD-auth.md with: Problem Statement, Success Criteria, Out of Scope, Technical Approach, Risk Flags, Estimated Effort
5. Gate 1 activates — you must type approve to continue

Step 5: Approve and build

After reviewing the plan, approve it. Then run the full pipeline:

/meow:cook

This executes Phases 2-6 automatically:

• Phase 2: The tester agent writes failing tests for the auth module
• Phase 3: The developer agent implements until tests pass (self-heals up to 3 times)
• Phase 4: The reviewer agent checks 5 dimensions (architecture, types, tests, security, performance). The security agent auto-inserts because this is auth-related.
• Gate 2: You approve the review verdict
• Phase 5: The shipper agent creates a conventional commit, pushes, and creates a PR
• Phase 6: The documenter updates docs, the analyst captures patterns

What MeowKit does automatically

Phase	Agent	Hook/Gate	What happens
0	orchestrator	—	Reads memory, classifies complexity, assigns model tier
1	planner	Gate 1	Creates plan, waits for human approval
2	tester	pre-implement.sh	Writes failing tests, blocks implementation without them
3	developer	post-write.sh	Implements code, security scan on every file write
4	reviewer + security	Gate 2	5-dimension audit + security audit, waits for approval
5	shipper	pre-ship.sh	Test + lint + typecheck, then commit → PR
6	documenter + analyst	—	Update docs, capture patterns to memory

Next workflow

→ Adding a Feature — how to add features after initial setup