wip-forge

Built for starting quickly without rebuilding the same foundation every time. Open a fresh project, have the stack and agent context ready, load the relevant skills immediately, and start making.

Quick Start

npx wip-forge my-project
cd my-project
bun dev

Update an existing scaffolded project:

npx wip-forge --upgrade

wip-forge sets up the app, the agent context, and the curated skills layer so the starter page can be deleted and work can begin. It is highly opinionated. The setup reflects a specific way of working: refining the foundation, updating the skills, and tightening the workflow over time.

It pairs with tommylower/wip-cortex, the public companion repo that holds the skills scaffolded projects load at .skills/wip-cortex/.

Learn more at waveinprogress.com.

Behavior Profiles

Each project ships with AGENTS.md as the shared instruction layer. During scaffold you can select fast, balanced, strict, or brutal, create a custom profile immediately with agent-interviewer, or skip and add one later through your agent. Selecting a preset writes the full profile into AGENTS.md.

The Stack

• Next.js App Router
• Bun
• Tailwind CSS
• shadcn/ui
• Framer Motion
• Supabase
• TypeScript strict mode
• OKLCH color workflow
• Vercel Analytics and Speed Insights
• Agentation and DialKit in dev mode

The Skills

wip-forge links the curated wip-cortex repo into:

.skills/wip-cortex/

For Claude slash command discovery, the scaffold also creates flat aliases under .claude/skills/ for a small selected set of skills. Right now that includes responsive-craft.

Core design skills include:

• ui-principles
• responsive-craft
• framer-motion
• css-interaction-tips
• gradients
• rams
• reference-patterns

Other categories include:

• dev-tools/ for agentation and dialkit
• workflows/ for planning, review, conventions, and setup
• design-systems/ for reference systems
• marketing/ for copy, SEO, and growth work

Your personal working skills can stay completely separate. wip-cortex is the public curated set for scaffolded projects.

Agent Context

Each project gets a shared agent context layer:

• .agents/ for project, architecture, design, tasks, tools, and skills context
• AGENTS.md as the single source of truth
• .claude/CLAUDE.md, .cursor/rules, .windsurfrules, .github/copilot-instructions.md, and .github/codex-instructions.md as pointers back to AGENTS.md

The scaffold also adds:

• design/ for Pencil files
• .gitattributes for .pen files
• .env.example and .env.local with Supabase placeholders

What --upgrade Does

Run npx wip-forge --upgrade from a scaffolded project root.

It updates:

• AGENTS.md
• tool config pointers
• .gitattributes
• the linked wip-cortex repo
• the default landing page if you have not customized it
• dev-only layout tooling for Agentation and DialKit

It does not touch:

• your filled-in .agents/*.md files
• your application code, except the default landing page and dev-tool lines in layout.tsx
• your design/ files
• your .env values

Repo Layout

wip-forge/
  cli/               # CLI logic
  repo-template/     # files copied into new projects

Related

• wip-cortex
• wip-forge

engineered by wip. WAVES DONT DIE.