wip-scaffold

Project scaffold for design-first codebases. Sets up Next.js, Tailwind, Supabase, and agent context so you start building immediately instead of configuring.

Pairs with tommylower/skills for design, dev-tool, and workflow knowledge that agents reference during development. Skills are symlinked into every project — when you add a new skill to the repo, every project picks it up automatically.

This is opinionated. It reflects how I work — if your stack or process is different, the skills repo is useful on its own without any of this.

what's in here

wip-scaffold/
  cli/               # wip-scaffold CLI
  repo-template/     # files copied into every new project

All reusable knowledge (conventions, stack choices, workflows, design patterns, dev tools) lives in tommylower/skills. The scaffold just links it in.

stack

| Layer | Choice | Why this one | |-------|--------|-------------| | Framework | Next.js (app router) | Server components, file-based routing, deploys to Vercel with zero config | | Runtime | Bun | Faster installs and scripts than Node, handles TypeScript natively | | Styling | Tailwind CSS | Utility-first, maps cleanly to design tokens, no context-switching to CSS files | | Components | shadcn/ui (adapted) | Accessible primitives you fully own — not a dependency, just source code you can change | | Animation | Framer Motion | Declarative, handles spring physics and layout animations without fighting the framework | | Database + Auth | Supabase | Postgres, auth, edge functions, realtime in one platform. Avoids stitching multiple services together | | Hosting | Vercel | Push to main deploys to production. Preview URLs for every branch | | Types | TypeScript (strict) | Catches problems before runtime. Strict mode because loose mode defeats the point | | Colors | OKLCH | Perceptually uniform — dark mode palettes that actually look consistent across hues |

Not everything here will match your preferences. The stack file and conventions are the most opinionated parts — read those first to see if this setup aligns with how you work.

wip-scaffold

npx wip-scaffold my-project       # create a new project
npx wip-scaffold --upgrade         # update an existing project (run from project root)

create

What it does:

1. Create project directory, git init
2. Scaffold Next.js with Bun — app router, TypeScript strict, ESLint + Prettier
3. Install Tailwind CSS, Framer Motion, shadcn/ui, Supabase client
4. Install Vercel Analytics + Speed Insights and add them to the root layout
5. Install Agentation (design annotations) and DialKit (live value tuning) and add both to the root layout (dev-only)
6. Copy repo-template into the project:
   • .agents/ — structured context that tells AI agents about your project, architecture, design system, and current tasks
   • AGENTS.md — universal agent instructions (single source of truth)
   • .claude/CLAUDE.md, .cursor/rules, .windsurfrules, .github/copilot-instructions.md, .github/codex-instructions.md — tool-specific pointers to AGENTS.md
   • design/ — directory for Pencil design files
   • .gitattributes — binary handling for .pen files
7. Create .env.example with Supabase placeholders
8. Detect or clone tommylower/skills, symlink as .claude/skills/wip/
9. Install /rams command (accessibility + visual design review)
10. Install /interview command (agent behavior profile generator)
11. Ask if you want to personalize agent behavior (runs the interviewer)
12. Initial commit

After running this, bun dev works and any AI agent you open the project with already has full context — your design system, your conventions, your tools.

upgrade

Run npx wip-scaffold --upgrade from an existing project root to pull in the latest scaffold files without touching your code or design work.

Updates (always overwritten — these are infrastructure, not content):

• AGENTS.md — universal agent instructions
• .claude/CLAUDE.md, .cursor/rules, .windsurfrules, .github/copilot-instructions.md, .github/codex-instructions.md — tool config pointers
• .gitattributes
• Skills — pulls latest from GitHub (git pull), then re-links all directories
• /rams command (re-installed globally)
• /interview command (re-installed globally)

Never touched:

• .agents/*.md — your project context (project, architecture, design, tasks)
• src/ — your source code
• design/ — your design files
• package.json, node_modules, .env — your dependencies and environment
• Any .agents/ template files you've already filled in (only creates missing ones)

staying up to date

npx wip-scaffold --upgrade

Pulls the latest skills from GitHub, re-links them, and updates scaffold infrastructure files. Your source code, design files, and project context are never touched.

If you're working across multiple projects, run --upgrade in each one. It takes a few seconds and keeps all your projects on the same skill versions.

skills

Skills are markdown files that give agents specialized knowledge. The CLI symlinks tommylower/skills into .claude/skills/wip/. Running --upgrade pulls the latest and re-links. Your own skills can live anywhere else under .claude/skills/ without conflicts.

The skills repo is organized into:

| Directory | What's in it | |-----------|-------------| | design/ | UI principles, animation (framer-motion), gradients, responsive design, accessibility (rams), CSS interaction tips, Figma MCP, wiretext, reference patterns | | dev-tools/ | Agentation (annotation toolbar + MCP), DialKit (live value tuning panel). For the full visual styling suite, check out interfacecraft.dev | | workflows/ | Claude Code patterns, agent swarm, codex review, agent interviewer, conventions, stack defaults, dev setup | | design-systems/ | Reference design systems (Nothing) — not auto-loaded, used on request | | marketing/ | Submodule → coreyhaines31/marketingskills — copywriting, SEO, CRO, paid ads, email |

See the skills README for full details on each skill.

repo-template

The .agents/ directory is the core of the template. It's a set of markdown files that agents read before starting any task. You fill these in with your project's specifics.

repo-template/
  .agents/
    project.md        # what the project is, audience, key decisions
    architecture.md   # stack, file structure, data model, services
    design.md         # colors, type scale, spacing, component patterns
    tasks.md          # current work, next up, open questions
    tools.md          # recommended tools (pencil.dev, pretext, context7)
    skills.md         # how the skills library connects
    README.md         # agent entry point — reads all other .agents/ files
  AGENTS.md                          # universal instructions (all tools read this)
  .claude/CLAUDE.md                  # Claude Code → reads AGENTS.md + claude-specific prefs
  .cursor/rules                      # Cursor → reads AGENTS.md
  .windsurfrules                     # Windsurf → reads AGENTS.md
  .github/copilot-instructions.md   # GitHub Copilot → reads AGENTS.md
  .github/codex-instructions.md     # Codex → reads AGENTS.md
  design/README.md                   # Pencil design file conventions
  README.md                          # Project README template
  .gitattributes                     # *.pen binary handling

AGENTS.md is the single source of truth. Each tool's config file is a one-line pointer to it. Tool-specific preferences (like Claude's ultrathink) stay in that tool's config only. This means the project works with any AI coding tool without maintaining separate instructions for each one.

how it all connects

wip-scaffold my-project
        │
        ├─ scaffolds Next.js + deps + agentation
        ├─ copies repo-template/
        │    ├─ .agents/          ← you fill in project specifics
        │    ├─ AGENTS.md         ← single source of truth for all AI tools
        │    └─ tool configs      ← one-line pointers to AGENTS.md
        │
        ├─ symlinks ~/.skills/ → .claude/skills/wip/
        │    ├─ wip/design/       UI, motion, accessibility, design references
        │    ├─ wip/dev-tools/    agentation, dialkit
        │    ├─ wip/workflows/    claude-workflow, agent-swarm, agent-interviewer
        │    ├─ wip/design-systems/ reference systems (on request)
        │    └─ wip/marketing/    copywriting, SEO, CRO, ads
        │
        ├─ installs /rams + /interview globally
        │
        └─ asks: personalize agent behavior? (y/N)

During development, the flow looks like:

1. Personalize — /interview generates your agent behavior profile (how agents should think, disagree, communicate)
2. Design — Figma MCP reads tokens + layouts, or wiretext for quick ASCII prototypes, or pencil.dev for visual design in the IDE
3. Build — agents reference ui-principles for spacing/type, responsive-design for fluid layouts, framer-motion for animation, gradients for color transitions
4. Polish — dialkit for tuning animation values, css-interaction-tips for micro-interactions
5. Review — /rams for accessibility + visual consistency audit, agentation for agent-driven design annotations

agent interviewer

Every scaffolded project installs /interview as a Claude Code command. It runs a short adaptive interview and produces a markdown behavior file with concrete operating rules — things like how much pushback you want, how agents should handle ambiguity, what AI habits to avoid.

The output is agent-agnostic. Save it as AGENTS.md, CLAUDE.md, or whatever your tool reads. It replaces writing a behavior profile from scratch.

The scaffold asks during project creation whether you want to run it. You can also run /interview anytime after setup. Ask for "strict mode" or "V2" during the interview to get a tighter, more exacting version.

related

• skills — design, dev-tool, workflow, and marketing skills linked into projects
• marketingskills — marketing skills by Corey Haines (via skills submodule)